155 lines
3.7 KiB
Markdown
155 lines
3.7 KiB
Markdown
# 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`
|
|
|