# 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

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

### Find Cross-Chain Transactions

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

### Find Protocol Users Across Chains

```cypher
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`