explorer-monorepo/docs/specs/multichain/entity-graph.md

Cross-Chain Entity Graph

Overview

This document specifies the cross-chain entity graph for tracking relationships between addresses, contracts, and protocols across multiple chains.

Graph Structure

See ../database/graph-schema.md for detailed Neo4j schema.

Node Types

• Address: Blockchain addresses (can exist on multiple chains)
• Contract: Smart contracts (chain-specific instances)
• Token: Token contracts
• Protocol: DeFi protocols (cross-chain presence)

Relationship Types

• TRANSFERRED_TO: Token transfers
• CALLED: Contract calls
• OWNS: Token ownership
• CLUSTERED_WITH: Address clustering (same entity)
• CCIP_MESSAGE_LINK: Cross-chain message links

Address Clustering

Clustering Heuristics

1. Multi-Signature Wallets:

• Addresses controlled by same set of signers
• High confidence

2. Transaction Patterns:

• Addresses that frequently transact together
• Similar transaction timing
• Medium confidence

3. Funding Patterns:

• Addresses funded from same source
• Sequential funding
• Medium confidence

4. Contract Deployment:

• Addresses deploying contracts with similar code
• Same deployer patterns
• Low-medium confidence

Confidence Scores

High (0.9+): Multi-sig, verified relationships Medium (0.7-0.9): Pattern-based clustering Low (0.5-0.7): Weak patterns, needs verification

Implementation

Algorithm:

1. Analyze transaction patterns
2. Calculate similarity scores
3. Cluster addresses above threshold
4. Store relationships in graph database

Contract/Protocol Tagging

Protocol Identification

Methods:

1. Known Address Lists: Maintain list of known protocol addresses
2. Code Similarity: Compare contract code
3. Interaction Patterns: Analyze usage patterns
4. Labels: User-submitted labels

Protocol Categories

• DEX: Decentralized exchanges
• Lending: Lending protocols
• Bridge: Cross-chain bridges
• NFT Marketplace: NFT trading platforms
• Governance: DAOs and governance protocols

Tagging System

Tags:

• Category tags (DEX, Lending, etc.)
• Protocol tags (Uniswap, Aave, etc.)
• Risk tags (verified, audited, etc.)

Cross-Chain Entity Resolution

Address Resolution

Challenge: Same entity may use different addresses on different chains

Solution:

• Use clustering to link addresses
• Use CCIP message links
• Use bridge transaction patterns

Entity Unification

Process:

1. Identify entity across chains
2. Create unified entity node
3. Link chain-specific addresses to unified entity
4. Aggregate metrics across chains

Graph Query Patterns

Find Entity Across Chains

MATCH (e:Entity)-[:HAS_ADDRESS]->(a:Address)
WHERE e.id = "entity_123"
RETURN a.address, a.chainId;

Find Cross-Chain Transactions

MATCH (a1:Address {address: "0x...", chainId: 138})
      -[:CCIP_MESSAGE_LINK]->
      (a2:Address {chainId: 1})
RETURN a2.address, a2.chainId;

Find Protocol Users Across Chains

MATCH (a:Address)-[r:INTERACTS_WITH]->(p:Protocol {name: "Uniswap"})
RETURN a.address, a.chainId, count(r) as interactions
ORDER BY interactions DESC;

Data Ingestion

Cross-Chain Data Sources

1. Blockchain Data: Indexed transactions and transfers
2. CCIP Messages: Cross-chain message links
3. Bridge Transactions: Bridge usage patterns
4. User Labels: User-submitted entity relationships

Update Frequency

Real-time: New transactions and transfers Batch: Clustering analysis (daily) On-demand: User-requested clustering

References

• Graph Database Schema: See ../database/graph-schema.md
• CCIP Integration: See ../ccip/ccip-tracking.md
• Multi-chain Indexing: See multichain-indexing.md