1_general_forum/currency-ledger/README.md

# 💰 Smartup Zero Currency Ledger System

A git-native, transparent, and democratically governed dual-currency system for collective ownership and fair compensation.

**Status**: ✅ **FULLY OPERATIONAL** - Complete system with live transparency on timeline0.org

---

## 🎯 What We Built

The **Currency Ledger System** is the financial backbone of Smartup Zero, implementing:

- **Smartup Credits (SC)**: 1 SC = €1 treasury claim for completed work
- **Social Karma (SK)**: Non-transferable reputation currency for community contributions  
- **Book of Owners**: Complete organizational chart with team memberships and role assignments
- **Progressive Transparency**: Public governance with strategic development protection
- **Democratic Validation**: Community oversight of all currency awards and policy changes
- **Pending SC System**: Phased validation for large retrospective awards (like founding work)

## 🚀 Live Public Transparency

**All currency data is publicly visible on timeline0.org:**

- 📖 **[Book of Owners](https://timeline0.org/smartup-zero/book-of-owners/)** - Live organizational chart
- 💰 **[Financial Transparency](https://timeline0.org/smartup-zero/financial-transparency/)** - Complete financial health
- 💱 **[Currency System](https://timeline0.org/smartup-zero/currency-system/)** - How it all works

*Pages auto-generate from CSV ledger data - radical transparency in action!*

## 💎 Revolutionary Founder Model

**Current Status**: 82,200 SC pending validation representing 10 years of R&D work

### Democratic Vesting Schedule
- **Design Phase**: 24,660 SC (30%) - Needs Team Captain validation
- **Production Phase**: 32,880 SC (40%) - Needs community vote  
- **Organization Phase**: 24,660 SC (30%) - Automatic at market success

### Integrity Principles
- ✅ **Cannot self-validate** - Founder subject to same democratic rules
- ✅ **Success alignment** - Vesting tied to collective achievement
- ✅ **Community oversight** - Every SC requires external approval
- ✅ **Transparent process** - All validation public and recorded

**This proves Smartup Zero's "no special founders" principle is real and enforceable.**

---

## 🏗️ System Architecture

```
currency-ledger/
├── ledger/                          # Transaction records (public)
│   ├── smartup-credits/             # Live SC awards and redemptions
│   ├── social-karma/               # SK awards and decay events
│   ├── pending-sc/                 # Awaiting democratic validation
│   └── treasury/                   # EUR balance and liability tracking
├── ownership/                       # Organizational structure (public)
│   ├── book-of-owners.csv          # Public ownership registry with aliases
│   ├── license-transactions.csv    # License purchase/upgrade history
│   └── identity-mapping.csv        # Private: real names ↔ aliases (NEVER COMMITTED)
├── policies/                        # Configuration and rules (public)
│   ├── credit-rates.yml            # SC award rates and ADM split rules
│   ├── karma-rules.yml             # SK categories, thresholds, decay rates
│   ├── validation-rules.yml        # Democratic oversight processes
│   ├── license-policies.yml        # License types and capabilities
│   └── organizational-structure.yml # Teams, roles, assignment rules
└── scripts/                         # Management and automation tools
    ├── validate-ledger.py          # System integrity checking
    ├── generate-reports.py         # Financial transparency reports
    ├── manage-owners.py            # License and ownership management
    ├── manage-organization.py      # Team and role assignments
    ├── validate-pending-sc.py      # Pending SC validation workflows
    ├── update-profile.py           # Personal information updates
    ├── generate-public-pages.py    # Auto-generate timeline0.org pages
    └── system-check.py             # Comprehensive system validation
```

## 📊 Current System Status

### Financial Health: ✅ **EXCELLENT**
- **Live SC Outstanding**: 0 SC (€0 liability)
- **Pending SC**: 82,200 SC (awaiting validation)
- **EUR Treasury**: €0 (no current obligations)
- **3x Rule**: ✅ COMPLIANT

### Organizational Status: ✅ **READY**
- **Total Owners**: 1 (robbert_founder)
- **Teams Formed**: 1 (Leadership Team)
- **Roles Assigned**: 1 (Founding Entrepreneur)
- **License Distribution**: 1 Work License

---

## 🚀 How to Use the System

### For Current Owner (robbert_founder)

```bash
# Check system health
python3 currency-ledger/scripts/system-check.py

# View organizational chart
python3 currency-ledger/scripts/manage-organization.py

# Generate transparency reports
python3 currency-ledger/scripts/generate-reports.py

# Update public website pages
python3 currency-ledger/scripts/generate-public-pages.py

# Update personal profile
python3 currency-ledger/scripts/update-profile.py
```

### For Future Team Captains

```bash
# Review pending SC validations
python3 currency-ledger/scripts/validate-pending-sc.py

# Validate founder's design phase work (24,660 SC)
# Process: Review work → Community discussion → Leadership vote → Validation
```

### For New Contributors

1. **Join**: Purchase license via Open Collective
2. **Onboard**: Get added to Book of Owners
3. **Contribute**: Complete tasks, earn SC/SK
4. **Progress**: Advance through license tiers
5. **Lead**: Become Team Captain, validate others' work

## 🔧 Key Operations

### Adding New Owners

```python
from scripts.manage_owners import OwnershipManager
manager = OwnershipManager()
manager.add_new_owner(
    real_name="Alice Johnson",
    email="alice@example.com", 
    display_name="alice_builder",
    license_type="work",
    payment_eur=200
)
```

### Processing SC Awards

1. **Complete Work**: Task finished with evidence
2. **Submit Claim**: Add line to smartup-credits/transactions.csv
3. **Team Review**: Team Captain validates work + SC claim
4. **Community Period**: 48h lazy consensus for transparency
5. **Official Award**: Merge PR = permanent SC record

### Treasury Management

```bash
# Monitor 3x rule compliance
python3 currency-ledger/scripts/validate-ledger.py

# Check redemption capacity
python3 currency-ledger/scripts/generate-reports.py
```

### Public Transparency Updates

```bash
# Regenerate all public pages with latest data
python3 currency-ledger/scripts/generate-public-pages.py

# Commit to make live on timeline0.org
git add docs/smartup-zero/
git commit -m "Update transparency pages"
git push origin main
```

## 🎯 Success Metrics

The currency system succeeds when:

- **Democratic**: All owners can see and influence how money flows
- **Fair**: Contributors earn proportional to verified value created
- **Sustainable**: Treasury growth keeps pace with SC awards
- **Scalable**: System works at 10x, 100x current contributor count
- **Aligned**: Individual incentives serve collective SDG mission
- **Transparent**: Every transaction auditable by anyone, anytime

## 🏆 What Makes This Revolutionary

| Traditional Startup Founder | Smartup Zero Founder |
|------------------------------|---------------------|
| Takes 20-50% equity immediately | ✅ 82,200 SC pending democratic validation |
| Can cash out through investment rounds | ✅ Cannot cash out until community succeeds |
| Success not tied to employee welfare | ✅ Subject to same rules as everyone else |
| No community oversight or transparency | ✅ Success completely tied to collective achievement |
| | ✅ Every transaction public and auditable |

**This is the future of organizational ownership** - where founders earn through validation, not privilege.

## 🔄 Integration Roadmap

### Phase 1: Current (Validation Phase)
- ✅ Complete currency system operational
- ✅ Public transparency live on timeline0.org
- ✅ Founding work audit pending validation
- 🎯 **Next**: Recruit Team Captains to validate first tranche

### Phase 2: Design Phase
- 🎯 Team Captains validate 24,660 SC (Design tranche)
- 🎯 Engelbot integration for automation
- 🎯 Open Collective treasury sync
- 🎯 Matrix/Element integration for notifications

### Phase 3: Production Phase
- 🎯 Community validates 32,880 SC (Production tranche)
- 🎯 Advanced reporting and analytics
- 🎯 Automated redemption processing
- 🎯 50+ owners with mature governance

### Phase 4: Organization Phase
- 🎯 Final 24,660 SC automatically vests at market success
- 🎯 Full production deployment
- 🎯 Template for future Smartups
- 🎯 Revolutionary model proven at scale

## 🤝 Contributing to the System

This currency system is itself a collective creation. Improvements welcome:

1. **Identify Enhancement**: System limitation or optimization opportunity
2. **Propose Solution**: Detailed proposal in General Forum
3. **Community Discussion**: Democratic debate and refinement
4. **Implementation**: Code changes with full testing
5. **Integration**: Merge with updated documentation

---

**Built with ❤️ by the Smartup Zero community**

This system embodies our core principle: Technology should serve collective human needs, built by and for the communities that use it, with full democratic accountability but protection from extraction.

**Ready to earn your first Smartup Credits?** Complete a task, submit your SC claim, and join the transparent future of work! 🚀