> ## Documentation Index
> Fetch the complete documentation index at: https://paralens.ai/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Choose a Dashboard Layout Based on Transaction Intent

> Use classification.intent_kind to select the right dashboard layout — token flow, DeFi position, bridge, or approval — for any Ethereum transaction.

ParaLens classifies every transaction into a specific intent kind. Use `classification.intent_kind` to select the right layout and prominently surface the most relevant data for that transaction type. Matching the layout to the intent ensures users see the most meaningful information first, rather than wading through fields that don't apply.

## Layout Selection Guide

### Token Flow Layout

**Intent kinds:** `Swap`, `AggregatedSwap`, `Arbitrage`, `AtomicArbitrage`, `FlashFundedArbitrage`, `MevBundle`

These transactions revolve around asset movement between tokens. Lead with the flow of value.

* Render `inventory_deltas` as a flow diagram showing tokens in and tokens out
* Surface `economics.net_usd_before_gas` and `economics.fee_usd` prominently
* Show `realized_pnl` if present (relevant for arbitrage and MEV intents)
* Display the route or protocol chain when available in `attribution`

### DeFi Position Layout

**Intent kinds:** `LendingDeposit`, `LendingWithdraw`, `Borrow`, `Repay`, `LiquidityProvision`, `LiquidityRemoval`, `Liquidation`

These transactions modify a user's on-chain financial position. Lead with the position change.

* Show `position_effects` first — the before/after state of the position is the headline
* Follow with token movement from `inventory_deltas`
* For `Liquidation`, highlight the liquidated position and the incentive received

### Transfer Layout

**Intent kinds:** `SimpleTransfer`, `BatchTransfer`, `TreasurySweep`, `BridgeDeposit`, `BridgeOutLocal`, `BridgeInLocal`

These transactions move assets from one address or chain to another. Clarity and direction are paramount.

* Show sender, recipient, and transferred amount in clearly labeled lanes
* For bridge intents, show source chain → destination chain prominently
* For `BatchTransfer`, summarize the number of recipients and total value

### Approval Layout

**Intent kinds:** `ApprovalOnly`, `ApprovalAndAction`

These transactions grant or modify a third-party's ability to spend tokens on the user's behalf.

* Lead with an approval card showing the spender address and approved token amount
* Flag unlimited approvals clearly — these carry significant risk
* For `ApprovalAndAction`, show the approval card first, then the action that followed

### Deployment Layout

**Intent kinds:** `ContractDeployment`

These transactions deploy a new smart contract to the chain.

* Show an execution card with gas used, `execution.gas_cost_usd`, and the deployed contract address
* Surface `pipeline_stats` in a developer-facing detail panel (collapse by default in consumer UIs)

### Failure Layout

**Intent kinds:** `TransactionReverted`

The transaction was included in a block but its execution reverted.

* Show an execution failure card prominently — `execution.reverted` will be `true`
* Display gas spent (`execution.gas_cost_usd`) since fees are still paid on reverted transactions
* Surface any revert reason or warnings from the `motifs` array

### Fallback Layout

**Intent kinds:** `UnknownComplexFlow`, `ContractInteraction`

These transactions could not be mapped to a specific intent, or represent complex multi-step interactions without a cleaner classification.

* Show the motif constellation grouped by `scope_id` — each motif represents a recognized sub-pattern within the transaction
* Display `inventory_deltas` as a summary if token movement occurred
* Avoid hiding data: users looking at an unknown flow are typically sophisticated and want detail

<Note>
  When you encounter an `intent_kind` value not listed above, treat it as `UnknownComplexFlow` and render the fallback layout. ParaLens may introduce new intent kinds in future schema versions without a breaking change. See [Versioning](/docs/guides/versioning) for client resilience guidance.
</Note>

## Always-Visible Fields

Regardless of layout, the following fields should always be displayed. They provide universal context that users need for every transaction type.

<CardGroup cols={2}>
  <Card title="Intent Label" icon="tag">
    `classification.intent_label` — human-readable description of the transaction intent. Use this as the page or card headline.
  </Card>

  <Card title="Confidence" icon="chart-bar">
    `classification.confidence` — how certain the classifier is. Surface low-confidence results with a visual indicator so users know to cross-check.
  </Card>

  <Card title="Net Value" icon="dollar-sign">
    `economics.net_usd_before_gas` — net USD value transferred or generated, before gas costs. Always check `available` before rendering `text`.
  </Card>

  <Card title="Gas Cost" icon="gas-pump">
    `execution.gas_cost_usd` — what the transaction cost in gas. Always check `available` before rendering `text`.
  </Card>

  <Card title="Transaction Signer" icon="key">
    `tx.signer` — the address that signed and paid for the transaction.
  </Card>

  <Card title="Actor" icon="user">
    `classification.actor` — the primary economic actor identified by the classifier, which may differ from the signer (e.g., in MEV bundles).
  </Card>

  <Card title="Etherscan Link" icon="arrow-up-right-from-square">
    `tx.etherscan_url` — always include a link to Etherscan so users can independently verify the transaction details.
  </Card>

  <Card title="Transaction Hash" icon="hashtag">
    `tx.hash` — display the shortened hash (first 6 + last 4 characters) as a copyable element for reference and support.
  </Card>
</CardGroup>

## Fields to Hide in Consumer UIs

The following fields are useful for developers and debugging but add noise in consumer-facing dashboards. Collapse or omit them by default.

* `pipeline_stats` — internal timing and processing metadata
* Raw JSON / full response dump
* `price_source` and `price_confidence` — pricing provenance details
* Dense motif lists — for non-technical users, summarize rather than enumerate

Expose these in an expandable "Developer details" panel for power users who need them.

## TypeScript Layout Switch

Use a switch statement to map `intent_kind` to a layout component or layout key. Using `string` as the type for `intent_kind` (rather than a strict union) ensures new values added by the API don't cause TypeScript errors.

```tsx theme={null}
// components/TxDashboard.tsx
import type { TxReport } from '@/types/paralens';

type LayoutKey =
  | 'token-flow'
  | 'defi-position'
  | 'transfer'
  | 'approval'
  | 'deployment'
  | 'failure'
  | 'fallback';

function getLayoutKey(intentKind: string): LayoutKey {
  switch (intentKind) {
    case 'Swap':
    case 'AggregatedSwap':
    case 'Arbitrage':
    case 'AtomicArbitrage':
    case 'FlashFundedArbitrage':
    case 'MevBundle':
      return 'token-flow';

    case 'LendingDeposit':
    case 'LendingWithdraw':
    case 'Borrow':
    case 'Repay':
    case 'LiquidityProvision':
    case 'LiquidityRemoval':
    case 'Liquidation':
      return 'defi-position';

    case 'SimpleTransfer':
    case 'BatchTransfer':
    case 'TreasurySweep':
    case 'BridgeDeposit':
    case 'BridgeOutLocal':
    case 'BridgeInLocal':
      return 'transfer';

    case 'ApprovalOnly':
    case 'ApprovalAndAction':
      return 'approval';

    case 'ContractDeployment':
      return 'deployment';

    case 'TransactionReverted':
      return 'failure';

    case 'UnknownComplexFlow':
    case 'ContractInteraction':
    default:
      // Treat any unrecognized intent_kind as the fallback layout.
      // New intent kinds may be added in future schema versions.
      return 'fallback';
  }
}

const layoutComponents: Record<LayoutKey, React.ComponentType<{ report: TxReport }>> = {
  'token-flow': TokenFlowLayout,
  'defi-position': DefiPositionLayout,
  'transfer': TransferLayout,
  'approval': ApprovalLayout,
  'deployment': DeploymentLayout,
  'failure': FailureLayout,
  'fallback': FallbackLayout,
};

export function TxDashboard({ report }: { report: TxReport }) {
  const layoutKey = getLayoutKey(report.classification.intent_kind);
  const Layout = layoutComponents[layoutKey];
  return <Layout report={report} />;
}
```

## Handling Unknown `intent_kind` Values

The `default` branch in the switch above is critical. ParaLens may introduce new `intent_kind` values in future minor releases without a schema version bump — this is an additive, non-breaking change. Always provide a fallback rather than throwing or rendering nothing.

A safe pattern:

```ts theme={null}
// If you log unknown intents, you can track new values as they appear
function getLayoutKey(intentKind: string): LayoutKey {
  const known = layoutMap[intentKind];
  if (!known) {
    console.info(`[ParaLens] Unknown intent_kind: "${intentKind}" — using fallback layout`);
    return 'fallback';
  }
  return known;
}
```

For the full versioning policy and a checklist of client resilience rules, see [Versioning](/docs/guides/versioning).