💰 Smartup Zero Currency Ledger (v2.4)

Last Updated: October 11 2025
Phase Context: Pre‑Validation (Mission 5 _6 _0)
Maintainers: Leadership Team + Operational Team

---

## 1️⃣ WHY — Purpose & Context

### Why It Exists The Currency Ledger is the immutable public memory of Smartup OS.
It records every identity, decision, task, and reward in a format that can never be altered — only appended.

It answers the question:

 “Who did what, when, under which constitutional rule?”

### Mission Alignment - Implements Ground Rules 1–5 (Prove Your Work, Earn Your Trust, Separate Wealth from Power, Protect the Treasury, Act in the Open).
- Forms the baseline for scientific testing of collective ownership hypotheses.
- Replaces traditional databases with an append‑only ledger governed by Git history + constitutional scripts.

👉 It is the truth layer that both Engelbot and Toolbox operate on.

---

## 2️⃣ HOW — Architecture & Operation

### Position in Smartup OS

flowchart TD
    MatrixUser[Matrix Users] --> Engelbot[🤖 Engelbot  - Node.js]
    Engelbot -->|HTTP| ToolboxAPI[🧰 Toolbox API - Flask]
    ToolboxAPI -->|subprocess| ToolboxScripts[Python Toolbox Scripts]
    ToolboxScripts -->|Forgejo REST API| Forgejo[📦 Forgejo Server]
    Forgejo -->|Commit CSV changes| Ledger[(💰 Currency Ledger Repo)]
    Ledger -->|Visible via timeline0.org| Public[🌐 Transparency Dashboard]

### Core Principles

Principle	Guarantee
Append‑only	Data only ever added, never modified or deleted.
Cryptographically versioned	Git commit history is the audit trail.
Role‑enforced writes	Only Toolbox scripts with constitutional checks may write.
Separation of concerns	Ledger = storage; Toolbox = execution; Engelbot = interface.
Read‑only for humans	Contributors read through Forgejo API or timeline0.org.

### Physical Structure (v2.4)

currency-ledger/
├── master-events.csv                 # Full audit log
├── ownership/                        # Identity & Licenses
│   ├── book-of-owners.csv
│   ├── identity-mapping.csv          # private (GDPR)
│   └── license-transactions.csv
├── ledger/                           # Organizational data
│   ├── teams/, roles/, objectives/
│   ├── task-management/              # tasks → claims → sessions
│   ├── smartup-credits/, pending-sc/, social-karma/
│   └── treasury/                     # treasury snapshots
├── assessment_reports/
├── founding-work-audit/
├── policies/                         # Constitution + rules
└── scripts/ (legacy)

Each CSV in ledger/ acts as a table within the institutional database of Smartup OS.

---

### Primary Data Flows

#### Identity & Onboarding → Passport Issuance

flowchart TD
A[create_owner.py]-->B[book-of-owners.csv]
B-->C[identity-mapping.csv]
A-->D[license-transactions.csv]
E[!ratify_ownership via Engelbot]-->F[connect_matrix_owner.py]
F-->B
F-->C
F-->G[owner_passports/ - Markdown + JSON]

#### Task & Credit Lifecycle

flowchart TD
A[create_task.py] --> B[task-budgets.csv]
B --> C[claim_task.py → task_claimed.csv]
C --> D[assign_task.py → captain approval]
D --> E[start_work.py / stop_work.py → work_clock.csv + session_logs.csv]
E --> F[assess_work.py → pending-sc/transactions.csv  - PENDING_SC ]
F --> G[validate_pending_sc.py → smartup-credits/transactions.csv  - SC_AWARD -]
G --> H[treasury/balance.csv - snapshot]
G --> I[smartup-credits/reviews.csv]
H & I --> J[master-events.csv - log/trail]

---

### Integration with Engelbot & Toolbox

Function	Handled By
Command input and conversation	Engelbot
Write validation & role checks	Toolbox scripts - through Toolbox API
Ledger storage & audit	Forgejo currency‑ledger repo
Public transparency	timeline0.org - static derived from ledger

Result: Every !command in Matrix produces a Git commit in Forgejo.

---

## 3️⃣ WHAT — Capabilities & Changelog (v2.4)

### Current Capabilities

Domain	Purpose	Primary Files
Identity	All owners + licenses + Matrix linking	ownership/
Organization	Teams / roles / objectives registries	ledger/teams/, roles/, objectives/
Execution	Tasks → claims → sessions recorded	ledger/task-management/
Finance (SC)	Pending + validated Smartup Credits	pending-sc/ , smartup-credits/
Treasury & Karma	Snapshots and reputation transactions	treasury/, social-karma/
Audit & Transparency	Event log + timeline0 exports	master-events.csv, assessment_reports/

---

### Changelog (v2.3 → v2.4)

Date	Change	Impact
2025‑10‑11	Aligned ledger interfaces with Toolbox API architecture	Engelbot writes now flow through API commits.
2025‑10‑10	Auto generation of treasury snapshots on every validation	Improved financial integrity checkpoints.
2025‑10‑08	master‑events.csv fields standardized	Consistent auditing across scripts.
2025‑10‑04	Wiki bootstrap + SLOG system integration	Ledger now feeds wiki dashboards on timeline0.org.
2025‑10‑01	Reverse‑3× rule validation hardened	Enforces treasury security during Validation phase.

---

### Upcoming v2.5 Objectives

Goal	Description	Owner
💾 Schema YAML refs	Centralize CSV header definitions (appendix F → policy YAML)	Science Team
📈 Automated ledger validation	Nightly check via validate_ledger.py --cron	Ops Team
🤝 Cross‑Smartup aggregation	Multi‑Smartup treasury snapshot standard	Leadership Team

---

### Testing Checklist

Check	Script / Command	Expected
Owner appears after onboarding	create_owner.py → book‑of‑owners	New row with UUID license_id
Task creation through Engelbot	!create_task → Forgejo commit	New task in task‑budgets
SC award pipeline	assess_work.py → validate_pending_sc.py	PENDING_SC → SC_AWARD → treasury snapshot
Ledger health	validate_ledger.py	All sections ✅
Audit trail	master-events.csv	Every action logged

---

## 4️⃣ HOW TO READ / USE THE LEDGER

• Humans: via Forgejo web interface or timeline0 exports.
• Bots (Engelbot): via Forgejo API GET /raw/<path> .
• Writers (Toolbox): only through Forgejo API PUT via forgejo_api.py.
• Analysts: clone repo read‑only to run reports or visualizations.

All data exported under open license for public audit.

---

## 5️⃣ REFERENCES & LINKS

Component	Path	Role
🧰 Toolbox (v2.4)	3_1_leadership_team/toolbox/	Write layer agents
🧰 Toolbox API (v1.0)	3_1_leadership_team/toolbox_api/	Flask execution service
🤖 Engelbot (v1.0)	3_7_operational_team/	Chat interface
📜 Policies/Constitution	2_workplace/currency-ledger/policies/	Rule definitions
🌐 timeline0.org	https://timeline0.org	Public transparency portal

---

### Mission Statement

“The Currency Ledger is the memory of collective work.
 Every Smartup contribution lives here — indelible, verifiable, and shared by all.”

---