Add full monorepo: virtual-banker, backend, frontend, docs, scripts, deployment

Co-authored-by: Cursor <cursoragent@cursor.com>
2026-02-10 11:32:49 -08:00
parent aafcd913c2
commit 88bc76da91
815 changed files with 125522 additions and 264 deletions
--- a/docs/specs/multichain/entity-graph.md
+++ b/docs/specs/multichain/entity-graph.md
@@ -0,0 +1,154 @@
+# 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`
+