> ## Documentation Index
> Fetch the complete documentation index at: https://docs.walletwall.org/llms.txt
> Use this file to discover all available pages before exploring further.
# Coinstellation
> Wallet relationship and movement context for readiness decisions โ counterparties, clusters, transaction paths, nodes, edges, click-to-explore, and NodeDetailPanel tabs.
# Coinstellation
Coinstellation is a supporting signal surface that adds wallet relationship and movement context to vault-readiness decisions. It renders the on-chain connections of an Ethereum wallet as an interactive node-edge visualization โ counterparties, clusters, and transaction paths โ built from read-only transaction history sourced from Etherscan, Alchemy, and The Graph. It explains the relationship context behind a readiness recommendation; it does not infer identity, intent, or ownership.
## Homepage Path Finder preview
The homepage includes a looping Coinstellation Path Finder preview
(`CoinstellationTracePath`). It shows a compact animated path through the
Coinstellation journey and links users into the full Coinstellation route.
The Path Finder is a visual navigation preview. It is not a live graph query and
does not replace the wallet graph returned by `GET /api/wallet`. The full
Coinstellation graph still loads only after a wallet address or ENS name is
submitted, then renders source-backed nodes, edges, sampling metadata, and data
quality indicators.
## Galaxy graph
The graph renders wallet addresses, tokens, DeFi protocols, NFTs, and counterparties as nodes connected by weighted edges. It is displayed in a 2D/3D interactive canvas using Three.js.
Nodes are laid out to emphasize relationship clusters: wallets with high transaction volume to the same protocol or counterparty appear closer together.
## Entry points
Coinstellation can be reached from:
* A direct wallet address or ENS name entered in the search bar
* Clicking a tile in Holder Wall
* Selecting a wallet from the Whale Watcher workspace
## Node types
| Type | Description |
| -------------- | ----------------------------------------------------------------------- |
| `wallet` | Ethereum address (EOA or contract wallet) |
| `token` | ERC-20 token contract |
| `defi` | DeFi protocol contract (Uniswap, Aave, Curve, etc.) |
| `nft` | NFT contract |
| `counterparty` | Address that transacted with the wallet but is not otherwise classified |
| `anomaly` | Address flagged by risk heuristics |
## Edge relationships
Edges represent transaction relationships derived from loaded Ethereum wallet activity:
* Wallet-to-token: the wallet holds or traded this token
* Token-to-protocol: the token flows through this protocol
* Token-to-counterparty: the token was sent to or received from this counterparty
Edge weight (`weightUSD`) is the USD-like value of cumulative transactions between the two nodes. `txCount` records the number of interactions.
## Click-to-explore
Clicking any node opens the NodeDetailPanel. Clicking an edge highlights the transaction path between the two connected nodes.
Double-clicking a counterparty node or wallet node initiates a graph expansion, loading that node's own transaction graph and appending its relationships to the current view.
## Interaction flow
```mermaid theme={null}
flowchart TD
accTitle: Coinstellation entry points and interaction flow
accDescr: Users reach Coinstellation from a direct wallet or ENS search, a Holder Wall tile, or the Whale Watcher workspace. The graph loads source-backed nodes, edges, and sampling metadata. Clicking a node opens the NodeDetailPanel; clicking an edge highlights the transaction path between the two connected nodes; double-clicking a counterparty or wallet node expands the graph by loading that node's own transaction graph.
search["Wallet address or ENS name
in search bar"]:::input
holder["Holder Wall tile"]:::input
whale["Whale Watcher workspace"]:::input
coingraph["Coinstellation graph
(nodes, edges, sampling metadata)"]:::process
detail["NodeDetailPanel
(Portfolio / Volume / Tx Count)"]:::output
path["Highlighted transaction path"]:::output
expand["Graph expansion
(loads node's own transaction graph)"]:::process
search --> coingraph
holder --> coingraph
whale --> coingraph
coingraph -- "click node" --> detail
coingraph -- "click edge" --> path
coingraph -- "double-click counterparty/wallet node" --> expand
classDef input fill:#FAFAF0,stroke:#B87333,color:#2B2118,stroke-width:1.5px;
classDef process fill:#B84923,stroke:#6B2412,color:#FFF7E8,stroke-width:1.5px;
classDef output fill:#9AAB89,stroke:#526246,color:#172014,stroke-width:1.5px;
```
*Coinstellation is reached from a direct search, a Holder Wall tile, or the Whale Watcher workspace. Clicking a node opens its detail panel, clicking an edge highlights the transaction path, and double-clicking a counterparty or wallet node expands the graph.*
## NodeDetailPanel tabs
The NodeDetailPanel has three tabs:
Token balances and estimated USD value held by the selected wallet node. Sourced from CoinGecko price data and on-chain balance calls.
Cumulative USD volume transacted between the selected node and its counterparties over the loaded transaction window. Derived from `weightUSD` on connected edges.
Number of transactions between the selected node and each connected node. Derived from `txCount` on connected edges.
## Observability badge
An observability badge in the graph header shows the data source and provider for the current wallet:
| `observability.source` | Badge text |
| ---------------------- | ----------------------- |
| `live` | `Live ยท ` |
| `mock` | `Demo` |
| `fallback` | `Fallback` |
The tooltip shows provider, partial flag, freshness, and response duration.
## Data sources
Coinstellation is powered by the `GET /api/wallet` endpoint. Provider selection is automatic:
| Condition | Provider |
| ----------------------- | ---------------------------------------------------- |
| `ETHERSCAN_API_KEY` set | Etherscan (live) |
| `ALCHEMY_API_KEY` only | Alchemy (live) |
| Neither key set | Mock wallet provider (deterministic, address-seeded) |
The mock provider never calls external APIs. It produces deterministic graph data seeded from the wallet address using `ethers.id`.
## Transaction sampling
The API loads up to a configured sample limit of normal transactions per wallet. The `transactionSample` field in the response reports:
Number of transactions loaded.
Configured limit.
True when the response hit the limit.
ISO timestamps of the loaded window.
When `isSampled` is true, the graph may be incomplete. A data-quality strip at the bottom of the screen notes partial data without alarming copy.
## Whale Watcher context
From any wallet node in Coinstellation, the Whale Watcher workspace can be opened for that wallet. This transitions from graph exploration to the full intelligence workspace.
## Label sanitization
Node labels are sanitized via `sanitizeLabel` before display. Phishing symbols and spam content are redacted. Raw counterparty labels from providers are never shown unmodified.
## Related surfaces
Coinstellation can be opened directly from a Holder Wall tile.
Selecting a wallet in the Whale Watcher workspace can open its Coinstellation graph.
Quantum Intelligence surfaces inside the Coinstellation NodeDetailPanel.