ARCHITECTURE.md

# ProofBridge Liner Architecture

## Overview

ProofBridge Liner is a decentralized security system for tokenized real-world assets (RWAs), implementing probabilistic fraud detection through multi-gateway document validation and threshold-based circuit breakers.

## Core Components

### Smart Contracts

#### CircuitBreaker.sol
- **Purpose**: Oracle-controlled circuit breaker for ERC-20 transfer gating
- **Key Functions**:
  - `validate(assetId, expectedHash)`: Checks proof integrity and circuit state
  - `updateProof(assetId, deedHash)`: Updates on-chain proof (oracle only)
  - `tripCircuit(reason)`: Halts all transfers (oracle only)
  - `reset()`: Restores normal operation (owner only)
- **Security**: Threshold signatures required for oracle operations
- **Gas Cost**: < 0.03 POL per validation

#### IProofHook.sol
- **Purpose**: Standard interface for ERC-20 integration
- **Integration**: 5-line hook in `_beforeTokenTransfer`
- **Compatibility**: Works with any ERC-20 implementation

### Prover Pipeline

#### Fetcher (`prover/fetcher.js`)
- **Responsibilities**:
  - Multi-gateway IPFS resolution (5+ nodes)
  - SHA-256 hash computation
  - Evidence collection and health scoring
  - Exponential backoff for failures
- **Output**: Asset status (fresh/mismatch/unreachable)

#### Validator (`prover/validator.js`)
- **Responsibilities**:
  - Deterministic deed structure validation
  - 6 regex-based integrity checks
  - Document schema compliance
- **Output**: Boolean validity flag

#### Scorer (`prover/scorer.js`)
- **Responsibilities**:
  - Beta-Binomial posterior probability calculation
  - TEE-deterministic validation override
  - Scenario classification (A/B/C)
  - Threshold-based trip decisions
- **Algorithm**:
  ```
  α = 1 + mismatches
  β = 10 + (total - mismatches)
  score = α / (α + β)

  // TEE Clamping Logic
  if (config.deterministicOverride && !validation.valid) {
      score = Math.max(score, config.deterministicFloor);
      isClamped = true;
  }

  trip if score > threshold
  ```
- **TEE Integration**: Hardware-enforced legal document schema validation overrides probabilistic consensus for structural fraud detection

#### Submitter (`prover/submitter.js`)
- **Responsibilities**:
  - Action planning based on scores
  - Threshold signature request generation
  - Attestation creation
- **Output**: Signed attestations for broadcasting

#### Broadcaster (`prover/broadcaster.js`)
- **Responsibilities**:
  - On-chain transaction submission
  - Gas estimation and optimization
  - Transaction monitoring
- **Security**: TSS quorum verification

### Supporting Systems

#### TSS Quorum
- **Nodes**: 5 independent signers
- **Threshold**: 3-of-5 for oracle operations
- **Implementation**: Docker-based for local testing

#### Dashboard (`dashboard/server.js`)
- **Purpose**: Real-time monitoring interface
- **Features**: Asset health visualization, circuit status, audit logs
- **Tech**: Express.js + WebSocket for live updates

## Technical Innovations

### Probabilistic Scoring
- **Bayesian Inference**: Quantifies uncertainty in multi-source validation
- **Scenario Differentiation**:
  - **A (Weak)**: Single gateway mismatch (transient)
  - **B (Strong)**: Multi-gateway consistent mismatch (adversarial)
  - **C (Unreachable)**: Network failure (retry logic)

### Fault Tolerance
- **Gateway Diversity**: 5+ IPFS nodes prevent single-point failures
- **Timeout Protection**: Per-command and global timeouts
- **Health Monitoring**: Consecutive failure tracking

### Integration Patterns
- **ERC-20 Hook**: Minimal 5-line integration
- **Chain Agnostic**: Works on any EVM-compatible chain
- **Oracle Flexibility**: Supports multiple TSS configurations

## Security Model

### Trust Assumptions
- **IPFS Network**: Decentralized storage integrity
- **TSS Quorum**: Threshold cryptography for oracle operations
- **Smart Contracts**: Audited OpenZeppelin patterns

### Threat Mitigation
- **Ghost-Risk**: Document tampering detection via multi-source validation
- **Oracle Compromise**: Threshold signatures prevent single-key failure
- **Network Attacks**: Circuit breaker provides fail-safe halting

### Attack Vectors Addressed
- **Document Forgery**: Hash verification across gateways
- **Gateway Compromise**: Quorum-based consensus
- **Oracle Manipulation**: Threshold cryptography
- **Sybil Attacks**: Multi-source validation
- **DDoS**: Circuit breaker emergency stop

## Performance Characteristics

### Latency
- **Validation**: < 5 seconds per asset
- **Circuit Trip**: Instant on-chain execution
- **Audit Cycle**: < 2 minutes for 1000 assets

### Scalability
- **Linear Growth**: O(n) with asset count
- **Parallel Processing**: Gateway resolution in parallel
- **Resource Efficient**: Minimal gas costs

### Reliability
- **Uptime**: 99.9% with fault tolerance
- **False Positives**: < 0.1% through probabilistic tuning
- **Recovery**: Automatic circuit reset after investigation

## Deployment Architecture

### Network Support
- **Primary**: Polygon Amoy (testnet), Polygon Mainnet
- **Compatible**: Any EVM chain with IPFS gateway access

### Infrastructure Requirements
- **Node.js**: >= 20.0
- **Foundry**: For contract development
- **Docker**: For TSS quorum (optional)
- **IPFS**: Gateway access for document resolution

### Configuration Files
- **assets.json**: Asset registry with IPFS CIDs
- **scoring.json**: Probabilistic and deterministic parameters
- **.env**: Environment variables and secrets

### Scoring Configuration (Production)
```json
{
  "jurisdiction": "South Africa",
  "deterministicFloor": 0.8,
  "thresholdA": 0.285,
  "thresholdB": 0.45,
  "minMismatchesB": 2
}
```

**TEE Integration Logic**:
```javascript
// CONDITION: Deterministic Silicon Gate
if (config.deterministicOverride && !validation.valid) {
    // Override probabilistic noise with legal certainty
    triggerScore = Math.max(triggerScore, config.deterministicFloor);
    isClamped = true;
}
```

## Future Extensions

### AI Enhancement
- **Document Analysis**: Hugging Face integration for content validation
- **Anomaly Detection**: ML-based pattern recognition
- **Automated Recovery**: Intelligent circuit reset decisions

### Cross-Chain
- **Interoperability**: Bridge protocols for multi-chain assets
- **Unified Oracles**: Cross-chain TSS coordination
- **Asset Tracking**: Multi-chain deed verification

### Enterprise Features
- **Audit Trails**: Comprehensive logging and reporting
- **Compliance**: Regulatory reporting automation
- **Integration APIs**: REST/WebSocket for third-party systems