381 lines
14 KiB
Markdown
381 lines
14 KiB
Markdown
# Currency Ledger System README
|
|
**Smartup Zero's Transparent, Democratic Currency Architecture**
|
|
|
|
# 💰 Smartup Zero Currency Ledger System
|
|
|
|
A git-native, transparent, and democratically governed dual-currency system for collective ownership and fair compensation.
|
|
|
|
## 🎯 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
|
|
|
|
## 🏗️ System Architecture
|
|
|
|
```
|
|
currency-ledger/
|
|
├── ledger/ # Transaction records (public)
|
|
│ ├── smartup-credits/
|
|
│ │ └── transactions.csv # All SC awards and redemptions
|
|
│ ├── social-karma/
|
|
│ │ └── transactions.csv # All SK awards and decay events
|
|
│ └── treasury/
|
|
│ └── balance.csv # EUR balance and SC 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 and approval processes
|
|
│ ├── license-policies.yml # License types and capabilities
|
|
│ └── organizational-structure.yml # Teams, roles, and assignment rules
|
|
├── scripts/ # Management and automation tools
|
|
│ ├── validate-ledger.py # Integrity checking and 3x rule validation
|
|
│ ├── generate-reports.py # Community transparency reports
|
|
│ ├── manage-owners.py # License management and upgrades
|
|
│ ├── manage-organization.py # Team and role assignments
|
|
│ ├── update-profile.py # Personal information updates
|
|
│ └── system-check.py # Comprehensive system validation
|
|
└── README.md # This documentation
|
|
```
|
|
|
|
## 🧠 Key Design Decisions
|
|
|
|
### Why Git-Native?
|
|
- **Immutable History**: Every transaction permanently recorded in version control
|
|
- **Democratic Review**: All changes go through standard PR/review process
|
|
- **Transparency**: Complete audit trail visible to all owners
|
|
- **Decentralized**: No single point of failure or control
|
|
|
|
### Why Dual Currency?
|
|
- **SC (Work Currency)**: Compensates direct task completion with EUR backing
|
|
- **SK (Social Currency)**: Recognizes community building, mentoring, governance
|
|
- **Prevents Gaming**: Can't buy influence, must earn through contribution
|
|
- **Balanced Incentives**: Rewards both individual output and collective health
|
|
|
|
### Why Progressive Transparency?
|
|
- **Public Governance**: All decisions, budgets, and awards visible to world
|
|
- **Protected Development**: Implementation details secure until strategic release
|
|
- **Meaningful Licenses**: Each tier provides genuine value and responsibility
|
|
- **Democratic Legitimacy**: Community oversight without compromising execution
|
|
|
|
### Why the 3x Rule?
|
|
- **SC Value Protection**: Outstanding SC ≤ 3x EUR treasury prevents inflation
|
|
- **Fiscal Discipline**: Forces sustainable growth and prevents over-promising
|
|
- **Redemption Guarantee**: Ensures SC holders can eventually claim EUR value
|
|
- **Community Trust**: Mathematical proof of financial responsibility
|
|
|
|
## 📊 How It Works
|
|
|
|
### The Flow: Work → SC → EUR
|
|
|
|
```mermaid
|
|
graph LR
|
|
A[Complete Task] --> B[Submit SC Claim]
|
|
B --> C[Team Captain Review]
|
|
C --> D[Community Validation]
|
|
D --> E[SC Minted & Recorded]
|
|
E --> F[Treasury Funding]
|
|
F --> G[Redemption Window]
|
|
G --> H[SC → EUR Conversion]
|
|
```
|
|
|
|
### License Progression System
|
|
|
|
| License | Price | Can Earn | Teams Access | Voting | Upgrade Path |
|
|
|---------|-------|----------|--------------|--------|--------------|
|
|
| **Campaign** | FREE | SK only | Media team | Yes | 100 SK → Watch |
|
|
| **Watch** | €100+ | SK only | Read-only | Yes | €200 → Work |
|
|
| **Work** | €200+ | SC + SK | All teams | Yes | €5000 → Organizational |
|
|
| **Organizational** | €5000+ | SC + SK | All teams | Yes (same weight) | N/A |
|
|
|
|
### ADM Triangle (90/10 Split)
|
|
- **Attacker (Senior)**: Does main work, earns 90% of task SC
|
|
- **Defender (Junior)**: Reviews work, learns skills, earns 10% of task SC
|
|
- **Midfielder (Bot)**: Automates process, ensures transparency
|
|
|
|
## 🚀 How to Use the System
|
|
|
|
### Initial Setup & Validation
|
|
|
|
```bash
|
|
# Check system health
|
|
python3 currency-ledger/scripts/system-check.py
|
|
|
|
# Validate ledger integrity
|
|
python3 currency-ledger/scripts/validate-ledger.py
|
|
|
|
# Generate transparency reports
|
|
python3 currency-ledger/scripts/generate-reports.py
|
|
```
|
|
|
|
### Owner Management
|
|
|
|
```bash
|
|
# View current organizational chart
|
|
python3 currency-ledger/scripts/manage-organization.py
|
|
|
|
# Manage licenses and ownership
|
|
python3 currency-ledger/scripts/manage-owners.py
|
|
|
|
# Update your personal profile
|
|
python3 currency-ledger/scripts/update-profile.py
|
|
```
|
|
|
|
### Adding New Owners
|
|
|
|
```python
|
|
# Example: Add new owner with work license
|
|
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
|
|
)
|
|
```
|
|
|
|
### Role Assignment Process
|
|
|
|
```python
|
|
# Example: Assign role to team member
|
|
from scripts.manage_organization import OrganizationManager
|
|
org = OrganizationManager()
|
|
org.assign_role("002", "4_3_1_backend_developer", "junior")
|
|
```
|
|
|
|
### Currency Transaction Workflow
|
|
|
|
1. **Task Completion**: Work completed and evidenced
|
|
2. **SC Claim**: Add transaction line to `smartup-credits/transactions.csv`
|
|
3. **Team Review**: Team Captain (Defender) reviews work + SC claim
|
|
4. **Community Period**: 48h lazy consensus for large amounts
|
|
5. **Merge**: PR merged = official SC award
|
|
6. **Git History**: Permanent record of transaction
|
|
|
|
#### Manual SC Award Example
|
|
|
|
```csv
|
|
# Add to currency-ledger/ledger/smartup-credits/transactions.csv
|
|
2025-08-04T16:00:00Z,SC,100,,alice_builder,task-456,Frontend component development,bob_captain,validation,https://forgejo.../issues/456
|
|
```
|
|
|
|
### Treasury Management
|
|
|
|
```bash
|
|
# Check treasury health and 3x rule compliance
|
|
python3 currency-ledger/scripts/validate-ledger.py
|
|
|
|
# View current balances and redemption capacity
|
|
python3 currency-ledger/scripts/generate-reports.py
|
|
```
|
|
|
|
### Policy Updates
|
|
|
|
All policy changes require community review:
|
|
|
|
1. **Propose**: Update YAML files in `policies/`
|
|
2. **Review**: Community discusses changes in General Forum
|
|
3. **Vote**: Binding vote if controversial (>2 objections)
|
|
4. **Implement**: Merge policy changes
|
|
5. **Apply**: New rates/rules take effect immediately
|
|
|
|
## 🔐 Security & Privacy
|
|
|
|
### What's Public (Committed to Git)
|
|
- All transaction records with public aliases
|
|
- Complete policy configurations
|
|
- Book of Owners with chosen display names
|
|
- Team and role assignments
|
|
- Treasury balance and SC liability
|
|
|
|
### What's Private (Never Committed)
|
|
- Real names and contact information (`identity-mapping.csv`)
|
|
- Personal addresses and payment details
|
|
- Private communications and internal discussions
|
|
|
|
### Privacy Controls
|
|
|
|
```bash
|
|
# Check .gitignore protection
|
|
git status # Should NOT show identity-mapping.csv
|
|
|
|
# Update your public display name
|
|
python3 currency-ledger/scripts/update-profile.py
|
|
```
|
|
|
|
## 📈 Monitoring & Reporting
|
|
|
|
### Regular Health Checks
|
|
|
|
```bash
|
|
# Daily: Validate system integrity
|
|
python3 currency-ledger/scripts/validate-ledger.py
|
|
|
|
# Weekly: Generate community reports
|
|
python3 currency-ledger/scripts/generate-reports.py
|
|
|
|
# Monthly: Check for license upgrades
|
|
python3 currency-ledger/scripts/manage-owners.py
|
|
```
|
|
|
|
### What to Monitor
|
|
|
|
- **Treasury Ratio**: SC outstanding vs EUR balance (must be ≤ 3x)
|
|
- **License Upgrades**: Campaign holders earning 100+ SK
|
|
- **Role Assignments**: Team balance and capacity
|
|
- **Transaction Volume**: SC/SK awards trending up/down
|
|
- **Community Health**: Active contributors and engagement
|
|
|
|
## 🔧 Integration Points
|
|
|
|
### Future Engelbot Integration
|
|
- **Automatic SC Minting**: When tasks marked complete
|
|
- **License Upgrades**: Auto-upgrade Campaign→Watch at 100 SK
|
|
- **Policy Enforcement**: Validate transactions against current policies
|
|
- **Notification System**: Alert community of major transactions
|
|
|
|
### Open Collective Integration
|
|
- **Treasury Sync**: Real-time EUR balance updates
|
|
- **Redemption Processing**: SC→EUR conversion automation
|
|
- **License Payments**: Direct payment processing
|
|
- **Financial Reporting**: Automated transparency reports
|
|
|
|
### Matrix/Element Integration
|
|
- **Transaction Announcements**: All SC/SK awards posted to General Forum
|
|
- **Democratic Voting**: Policy changes voted in General Forum
|
|
- **Team Coordination**: Role assignments announced in team channels
|
|
|
|
## 🚨 Common Operations
|
|
|
|
### Emergency Procedures
|
|
|
|
# Suspend problematic transaction
|
|
git revert [commit-hash] # Reverses SC award
|
|
|
|
# Fix policy error
|
|
# Edit policy file → Create PR → Community review → Merge
|
|
|
|
# Backup system state
|
|
cp -r currency-ledger/ currency-ledger-backup-$(date +%Y%m%d)
|
|
Troubleshooting
|
|
bash
|
|
# Script not working?
|
|
chmod +x currency-ledger/scripts/*.py
|
|
|
|
# YAML syntax error?
|
|
python3 -c "import yaml; yaml.safe_load(open('currency-ledger/policies/[file].yml'))"
|
|
|
|
# CSV format issue?
|
|
python3 -c "import csv; list(csv.DictReader(open('currency-ledger/ledger/[file].csv')))"
|
|
|
|
# Identity mapping accidentally committed?
|
|
git rm --cached currency-ledger/ownership/identity-mapping.csv
|
|
echo "ownership/identity-mapping.csv" >> currency-ledger/.gitignore
|
|
|
|
📚 Understanding the System
|
|
For New Contributors
|
|
Read: This README and policy files in policies/
|
|
Observe: Check current Book of Owners and recent transactions
|
|
Join: Purchase appropriate license via Open Collective
|
|
Contribute: Start with small tasks, earn SK through community help
|
|
Progress: Advance licenses as you demonstrate value and commitment
|
|
For Team Captains
|
|
|
|
# Weekly team review
|
|
python3 currency-ledger/scripts/manage-organization.py
|
|
|
|
# Approve team SC awards (as Defender in ADM triangle)
|
|
# Review → Validate work → Approve PR with SC transaction
|
|
|
|
# Monitor team health
|
|
python3 currency-ledger/scripts/generate-reports.py
|
|
For Leadership Team
|
|
bash
|
|
# Monitor system health
|
|
python3 currency-ledger/scripts/validate-ledger.py
|
|
|
|
# Oversee major policy changes
|
|
# Review community proposals → Facilitate votes → Implement decisions
|
|
|
|
# Quarterly strategic reviews
|
|
python3 currency-ledger/scripts/generate-reports.py
|
|
🎯 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
|
|
|
|
Important Warnings
|
|
Do NOT
|
|
Never commit identity-mapping.csv to git (personal data)
|
|
Never manipulate transaction history without community approval
|
|
Never exceed 3x treasury rule (automated checks prevent this)
|
|
Never award SC without completed, verified work
|
|
Never bypass democratic approval for major policy changes
|
|
Always
|
|
Always validate transactions before committing
|
|
Always document SC awards with evidence links
|
|
Always respect community review periods
|
|
Always backup before major changes
|
|
Always maintain radical transparency principles
|
|
|
|
🔄 Version History
|
|
v0.1 (2025-08-04): Initial currency ledger system
|
|
v0.2 (Coming): Engelbot integration and automation
|
|
v0.3 (Coming): Advanced reporting and analytics
|
|
v1.0 (Coming): Full production deployment with Open Collective sync
|
|
🤝 Contributing to the System
|
|
This currency system is itself a collective creation. Improvements welcome:
|
|
|
|
Identify Issue: System limitation or enhancement opportunity
|
|
Propose Solution: Create detailed proposal in General Forum
|
|
Community Discussion: Democratic debate and refinement
|
|
Implementation: Code changes with full testing
|
|
Integration: Merge with documentation updates
|
|
|
|
📞 Support
|
|
General Questions: Post in General Forum (1_general_forum)
|
|
Technical Issues: Create issue in repository
|
|
Policy Disputes: Democratic resolution via community vote
|
|
Privacy Concerns: Contact Leadership Team directly
|
|
|
|
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! 🚀
|
|
|
|
## 🏗️ Founding Work Audit: A Case Study in Democratic Integrity
|
|
|
|
The robbert_founder founding work audit demonstrates how Smartup Zero's democratic principles apply even to founders:
|
|
|
|
**The Challenge**: How to fairly value 10 years of R&D and development work without undermining democratic governance?
|
|
|
|
**The Solution**: Pending SC with phased validation
|
|
- **82,200 SC total** (3,210 hours @ €25.60/hour average)
|
|
- **Phased vesting** tied to collective success
|
|
- **Democratic validation** by future Team Captains and community
|
|
- **No self-validation** - founder cannot approve own work
|
|
|
|
**The Integrity Signal**: This proves that Smartup Zero's "no special founders" principle is real and enforceable.
|
|
|
|
### Vesting Schedule
|
|
- **30%** (24,660 SC) - Team Captain validation
|
|
- **40%** (32,880 SC) - Community vote
|
|
- **30%** (24,660 SC) - Market success
|
|
|
|
This creates a founder whose success is **completely tied to collective success** - the opposite of traditional startup extraction.
|