14 KiB
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
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
# 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
# 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
# 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
# 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
- Task Completion: Work completed and evidenced
- SC Claim: Add transaction line to
smartup-credits/transactions.csv - Team Review: Team Captain (Defender) reviews work + SC claim
- Community Period: 48h lazy consensus for large amounts
- Merge: PR merged = official SC award
- Git History: Permanent record of transaction
Manual SC Award Example
# 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
# 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:
- Propose: Update YAML files in
policies/ - Review: Community discusses changes in General Forum
- Vote: Binding vote if controversial (>2 objections)
- Implement: Merge policy changes
- 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
# 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
# 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.