<!--
NON-NORMATIVE DOCUMENT

This file is historical/legacy/audit material and may contain aspirational language.
The canonical, current claims & limits are in: docs/CLAIMS_AND_LIMITS.md
-->

# Builder Belief Bonds (UDB V3)

## Overview

**Builder Belief Bonds** integrate the comprehensive belief scoring system into Universal Dignity Bonds, creating an economic mechanism that recognizes REAL builder value.

This is the first bond type that values **building > transacting** by pulling from 4 data sources:

1. **On-Chain Activity** (20%) - Base mainnet transactions
2. **GitHub Builder Metrics** (40%) - Commits, repos, code
3. **Enhanced GitHub** (30%) - Revolutionary contributions
4. **X/Twitter Social Proof** (10%) - Community impact

## Philosophy

### Core Principle

Every builder has inherent dignity, and building revolutionary technology should be economically rewarded MORE than just transacting.

### Key Innovations

1. **Multi-Source Recognition** - Integrates on-chain, GitHub, and social data
2. **Building Over Transacting** - 70% weight on GitHub contributions vs 20% on-chain
3. **Revolutionary Premium** - Unprecedented innovations earn higher multipliers
4. **Sustained Building** - Long-term contributions compound over time
5. **Dignity Floor** - Every builder's bond retains 50% value minimum

## Architecture

```
┌─────────────────────────────────────────────────────────────┐
│            Builder Belief Bonds (UDB V3)                     │
├─────────────────────────────────────────────────────────────┤
│                                                              │
│  ┌──────────────────────────────────────────────────────┐   │
│  │  Comprehensive Belief Scorer (4 Sources)             │   │
│  │                                                       │   │
│  │  • On-Chain (20%):   Base transactions, ethics       │   │
│  │  • GitHub (40%):     Commits, repos, impact          │   │
│  │  • Enhanced (30%):   Revolutionary detection         │   │
│  │  • Social (10%):     X/Twitter engagement            │   │
│  └──────────────────────────────────────────────────────┘   │
│                          │                                   │
│                          ▼                                   │
│  ┌──────────────────────────────────────────────────────┐   │
│  │  Belief Multiplier (1.0x - 2.0x)                     │   │
│  │                                                       │   │
│  │  Spark → Glow → Burner → Ascendant                  │   │
│  │  → Immortal Flame → Revolutionary → Legendary        │   │
│  └──────────────────────────────────────────────────────┘   │
│                          │                                   │
│                          ▼                                   │
│  ┌──────────────────────────────────────────────────────┐   │
│  │  Bond Appreciation Formula                           │   │
│  │                                                       │   │
│  │  Value = Stake × Belief_Delta × Tier_Mult × Time    │   │
│  └──────────────────────────────────────────────────────┘   │
│                                                              │
└─────────────────────────────────────────────────────────────┘
```

## Economic Mechanism

### Bond Appreciation Formula

```
Appreciation = Stake × Belief_Delta × Tier_Multiplier × Time_Multiplier
```

**Components:**

1. **Stake** - Initial investment (VAULT tokens)
2. **Belief Delta** - Improvement in comprehensive belief score
3. **Tier Multiplier** - Bonus for advancing through tiers
4. **Time Multiplier** - Compounding for sustained building

### Example Calculation

**Scenario:** Early-stage builder with high growth potential

```
Initial State:
- Stake: 1000 VAULT
- Baseline: 1.05x (Spark tier)
- GitHub: 5 repos, basic activity

After 1 Year:
- Current: 1.5x (Immortal Flame tier)
- GitHub: 20 repos, revolutionary project detected
- On-chain: Consistent Base transactions

Calculation:
- Belief Delta: 0.45 (1.5 - 1.05)
- Tier Multiplier: 2.0x (advanced 4 tiers)
- Time Multiplier: 2.0x (1 year sustained)
- Appreciation: 1000 × 0.45 × 2.0 × 2.0 = 1800 VAULT

Final Value: 2800 VAULT (180% return)
```

### Tier System

| Multiplier | Tier | Description |
|------------|------|-------------|
| 1.9+ | 🚀 **Legendary Builder** | Unprecedented revolutionary contributions |
| 1.7 - 1.9 | 💎 **Revolutionary** | Groundbreaking innovations |
| 1.5 - 1.7 | 🔥 **Immortal Flame** | Exceptional builder + believer |
| 1.3 - 1.5 | ⭐ **Ascendant** | Strong contributions |
| 1.15 - 1.3 | ✓ **Burner** | Good contributions |
| 1.05 - 1.15 | ○ **Glow** | Active participation |
| < 1.05 | · **Spark** | Early stage |

**Tier Progression Bonus:** Each tier advanced = +20% multiplier

### Time Multipliers

| Time | Multiplier | Description |
|------|------------|-------------|
| < 1 month | 1.0x | Just started |
| 1-3 months | 1.1x | Early building |
| 3-6 months | 1.2x | Consistent |
| 6-12 months | 1.5x | Sustained |
| 1-2 years | 2.0x | Long-term |
| 2-5 years | 3.0x | Dedicated |
| 5+ years | 5.0x | Legendary |

## Usage

### Create Builder Profile

```python
from vaultfire.advanced_bonds.builder_belief_bonds import BuilderBeliefBondsEngine

# Initialize engine
engine = BuilderBeliefBondsEngine()

# Create builder profile linking wallet, GitHub, X
profile = engine.create_builder_profile(
    builder_id="ghostkey316",
    wallet_id="bpow20.cb.id",
    github_username="Ghostkey316",
    x_username="ghostkey316"
)

# Profile automatically fetches comprehensive belief score
print(f"Baseline multiplier: {profile.baseline_belief['multiplier']:.4f}x")
print(f"Baseline tier: {profile.baseline_belief['tier']}")
```

### Stake in Builder

```python
# Staker creates bond
bond = engine.stake_in_builder(
    staker_id="early_believer_1",
    builder_id="ghostkey316",
    stake_amount=1000.0  # VAULT tokens
)

print(f"Bond ID: {bond.bond_id}")
print(f"Initial value: {bond.current_value} VAULT")
```

### Update Builder Belief Score

```python
# When builder ships code, improves metrics, grows community
result = engine.update_builder_belief("ghostkey316")

print(f"Old multiplier: {result['old_multiplier']:.4f}x")
print(f"New multiplier: {result['new_multiplier']:.4f}x")
print(f"Delta: {result['delta']:.4f}")
print(f"Stakers paid: {result['stakers_paid']}")
print(f"Total appreciation: {result['total_appreciation']} VAULT")

# Each staker automatically receives appreciation
for staker in result['staker_details']:
    print(f"  {staker['staker_id']}: +{staker['appreciation']} VAULT")
```

### Get Builder Stats

```python
stats = engine.get_builder_stats("ghostkey316")

print(f"Current multiplier: {stats['current_multiplier']:.4f}x")
print(f"Belief delta: {stats['belief_delta']:.4f}")
print(f"Tier progression: {stats['tier_progression']}")
print(f"Total stakers: {stats['total_stakers']}")
print(f"Total staked: {stats['total_staked']} VAULT")
print(f"Current value: {stats['total_current_value']} VAULT")
print(f"Community belief: {stats['community_belief']:.2f}x")
```

### Get Staker Portfolio

```python
portfolio = engine.get_staker_stats("early_believer_1")

print(f"Total bonds: {portfolio['total_bonds']}")
print(f"Total staked: {portfolio['total_staked']} VAULT")
print(f"Current value: {portfolio['total_current']} VAULT")
print(f"Total earnings: {portfolio['total_earnings']} VAULT")
print(f"ROI: {portfolio['roi']:.2f}%")
```

### Compare Builders

```python
# Compare investment returns between two builders
comparison = engine.compare_builders("builder_a", "builder_b")

print(f"Builder A ROI: {comparison['builder_1']['roi_percent']:.2f}%")
print(f"Builder B ROI: {comparison['builder_2']['roi_percent']:.2f}%")
print(f"Better investment: {comparison['better_investment']}")
```

## Use Cases

### 1. Early-Stage Builder Support

**Scenario:** Bet on builder with high growth potential

```python
# Builder just starting: 1.05x (Spark)
profile = engine.create_builder_profile(
    builder_id="new_builder",
    wallet_id="new.cb.id",
    github_username="new_coder"
)

# Early believer stakes 5000 VAULT
bond = engine.stake_in_builder("early_believer", "new_builder", 5000.0)

# After 6 months: Builder ships revolutionary project, reaches 1.6x (Immortal Flame)
# Delta: 0.55, Tier mult: 2.0, Time mult: 1.2
# Appreciation: 5000 × 0.55 × 2.0 × 1.2 = 6600 VAULT
# Final: 11,600 VAULT (132% return in 6 months)
```

### 2. Open Source Developer Funding

**Scenario:** Recognize unpaid open source work

```python
# OSS maintainer with strong GitHub but low on-chain
profile = engine.create_builder_profile(
    builder_id="oss_hero",
    github_username="rails"  # Example: prominent OSS contributor
)

# Community stakes in their work
for supporter in ["company_a", "company_b", "individual_c"]:
    engine.stake_in_builder(supporter, "oss_hero", 1000.0)

# As they continue building, bonds appreciate
# GitHub weight (70%) ensures OSS work is valued more than transactions
```

### 3. Revolutionary Project Backing

**Scenario:** Support unprecedented innovation

```python
# Builder working on revolutionary tech (detected by enhanced GitHub scorer)
profile = engine.create_builder_profile(
    builder_id="revolutionary_dev",
    github_username="vitalik"  # Example: revolutionary contributor
)

# High belief score due to revolutionary keywords, technical depth
# Baseline: 1.7x (Revolutionary)

# Visionary investors stake large amounts
bond = engine.stake_in_builder("visionary_vc", "revolutionary_dev", 100000.0)

# As project progresses toward Legendary (1.9x+)
# Even small delta has huge $ impact due to large stake
```

### 4. Community Builder Recognition

**Scenario:** Value thought leadership and social impact

```python
# Builder with strong X/Twitter presence + GitHub + on-chain
profile = engine.create_builder_profile(
    builder_id="community_leader",
    wallet_id="leader.cb.id",
    github_username="leader_dev",
    x_username="leader_dev"
)

# All 4 data sources contribute
# Social proof (10%) captures community impact beyond code

# Bonds appreciate as they build AND grow community
```

## Integration with Vaultfire

### Belief-Weighted Staking

Builder Belief Bonds can integrate with other Vaultfire mechanisms:

1. **Partner Protocols** - Recognize partner ecosystem builders
2. **Impact Bonds** - Combine belief metrics with impact measurement
3. **Reciprocal Belief Bonds** - Mutual staking between builders
4. **Universal Dignity Bonds V1/V2** - Hybrid human flourishing + builder belief

### Smart Contract Integration

```solidity
// Example Solidity integration (conceptual)
contract BuilderBeliefBond {
    struct Bond {
        address staker;
        bytes32 builderCommitment;  // Privacy-preserving
        uint256 initialStake;
        uint256 currentValue;
        uint256 baselineMultiplier;  // Scaled by 1000 (1500 = 1.5x)
        uint256 createdAt;
    }

    function updateBeliefScore(
        bytes32 builderCommitment,
        uint256 newMultiplier,
        bytes calldata zkProof  // Zero-knowledge proof of belief score
    ) external {
        // Verify ZK proof
        require(verifyBeliefProof(zkProof), "Invalid proof");

        // Update all bonds for this builder
        // Calculate appreciation
        // Pay stakers
    }
}
```

## Privacy Considerations

### Privacy-Preserving Mode

For builders who want privacy:

```python
from vaultfire.advanced_bonds.builder_belief_bonds import BuilderBeliefBond
from vaultfire.advanced_bonds.universal_dignity_bonds_v2 import create_beneficiary_commitment

# Create anonymous commitment
builder_secret = "random_secret_12345"
commitment = create_beneficiary_commitment(builder_secret)

# Bond uses cryptographic commitment instead of builder_id
# Only builder knows the secret to claim appreciation
```

### Data Sovereignty

- **On-Chain Data:** Public blockchain (Base mainnet)
- **GitHub Data:** Public repos only (respects GitHub privacy settings)
- **X/Twitter Data:** Public profile + tweets only
- **No Private Data:** Never accesses private repos, DMs, or non-public info

## Comparison with UDB V1 and V2

| Feature | UDB V1 | UDB V2 | Builder Belief Bonds (V3) |
|---------|--------|--------|---------------------------|
| **Focus** | Human flourishing | Privacy-preserving flourishing | Builder contributions |
| **Data Sources** | Manual flourishing scores | ZK proofs of flourishing | 4 automated sources |
| **Privacy** | Low (tracks person_id) | High (zero-knowledge) | Medium (public data only) |
| **Metrics** | Health, connection, growth, dignity, purpose | Same (encrypted) | On-chain, GitHub, social |
| **Multipliers** | Constraint-based (disability, poverty) | Same (ZK-proven) | Belief-based (tier progression) |
| **Target Use** | Supporting disadvantaged humans | Same (private) | Recognizing builders |
| **Economic Mechanism** | Delta × Constraint × Time | Same | Belief Delta × Tier × Time |

**When to Use Each:**

- **V1:** Traditional human dignity support (education, elder care, etc.)
- **V2:** Privacy-first human dignity support (sensitive populations)
- **V3:** Builder recognition (developers, open source, protocol builders)

## Testing

Run comprehensive tests:

```bash
# All Builder Belief Bonds tests
python -m pytest tests/advanced_bonds/test_builder_belief_bonds.py -v

# Specific test categories
python -m pytest tests/advanced_bonds/test_builder_belief_bonds.py::TestBuilderProfile -v
python -m pytest tests/advanced_bonds/test_builder_belief_bonds.py::TestEconomicMechanism -v
python -m pytest tests/advanced_bonds/test_builder_belief_bonds.py::TestIntegrationWithComprehensiveScorer -v
```

Test coverage:

- ✓ Builder profile creation
- ✓ Belief score fetching and delta calculation
- ✓ Tier progression tracking
- ✓ Bond appreciation mechanics
- ✓ Time multiplier scaling
- ✓ Dignity floor enforcement
- ✓ Multi-staker payouts
- ✓ Portfolio management
- ✓ Builder comparison
- ✓ Integration with comprehensive scorer
- ✓ Philosophy alignment (building > transacting)

## Future Enhancements

### Planned Features

1. **Multi-Chain Support** - Ethereum, Polygon, Arbitrum belief scoring
2. **Code Quality Analysis** - AST parsing to detect code complexity
3. **Commit Quality Scoring** - Analyze commit messages, diff sizes
4. **Network Effects** - Track collaborative contributions
5. **Long-Term Impact Weighting** - Older, sustained projects valued higher
6. **DAO Integration** - Governance based on builder belief scores
7. **Liquidity Pools** - Trade builder bonds on DEXes
8. **NFT Representation** - Each bond as unique NFT

### Research Areas

1. **Optimal Weighting** - Experiment with data source weights
2. **Anti-Gaming** - Prevent Sybil attacks, fake contribution inflation
3. **Fair Launch Detection** - Recognize genuine projects vs pumps
4. **Cross-Platform Identity** - Link GitHub, wallet, X without doxxing
5. **Reputation Staking** - Stake on builder reputation, not just code

## Philosophy

### Why Builder Belief Bonds Matter

Current DeFi mechanisms value:
- ✗ Token holdings (plutocracy)
- ✗ Trading volume (speculation)
- ✗ Gas spent (wealth display)

Builder Belief Bonds value:
- ✓ Code shipped (actual building)
- ✓ Revolutionary innovations (unprecedented tech)
- ✓ Sustained contributions (long-term commitment)
- ✓ Community impact (thought leadership)

### Building > Transacting

**The Math:**

- On-chain: 20% weight
- GitHub: 70% weight (builder 40% + enhanced 30%)
- Social: 10% weight

This mathematically ensures that building code is valued 3.5x more than just transacting.

### Every Builder Has Dignity

**Dignity Floor = 50%**

Even if belief score drops, bonds retain 50% of stake. This recognizes:
- Builders have lives (health issues, family)
- Not every quarter is productive
- Past contributions still matter
- Human dignity is inherent

## Resources

- **Comprehensive Belief Scorer:** `engine/comprehensive_belief_scorer.py`
- **Documentation:** `docs/COMPREHENSIVE_BELIEF_SCORING.md`
- **Tests:** `tests/advanced_bonds/test_builder_belief_bonds.py`
- **Base Chain Fetcher:** `engine/base_chain_fetcher.py`
- **GitHub Scorers:** `engine/github_builder_scorer.py`, `engine/github_enhanced_scorer.py`
- **Social Scorer:** `engine/twitter_social_scorer.py`

## Contributing

To improve Builder Belief Bonds:

1. **Add Data Sources** - More platforms (GitLab, npm, crates.io)
2. **Refine Weighting** - Experiment with optimal data source ratios
3. **Build Tools** - Dashboards, analytics, visualization
4. **Write Docs** - Tutorials, guides, examples
5. **Create Tests** - Edge cases, integration tests, fuzz testing

## License

Same as Vaultfire core (check root LICENSE file).

## Support

Questions or issues:
- GitHub Issues: [vaultfire/issues](https://github.com/Ghostkey316/vaultfire/issues)
- Documentation: This file + `COMPREHENSIVE_BELIEF_SCORING.md`
- Tests: See `test_builder_belief_bonds.py` for examples

---

**Builder Belief Bonds: Recognizing Real Builder Value**

*Because building revolutionary technology should be worth more than just holding tokens.*
