diff --git a/.gitleaksignore b/.gitleaksignore new file mode 100644 index 0000000..eec56fc --- /dev/null +++ b/.gitleaksignore @@ -0,0 +1,2 @@ +# Public on-chain addresses referenced in synthesis — not secrets. +docs/synthesis.md:generic-api-key:314 diff --git a/docs/synthesis.md b/docs/synthesis.md new file mode 100644 index 0000000..fd19e83 --- /dev/null +++ b/docs/synthesis.md @@ -0,0 +1,346 @@ +# The Token Engineering Commons: A Mechanism Post-Mortem + +*An empirical analysis of the TEC's augmented bonding curve, conviction voting, and treasury dynamics from Hatch to shutdown (2021–2025).* + +--- + +## 1. Introduction + +The Token Engineering Commons (TEC) was one of the most ambitious experiments in applied token engineering: a DAO that deployed an [Augmented Bonding Curve](https://forum.tecommons.org/t/augmented-bonding-curve-an-introduction-to-the-abc/497) (ABC) as its primary market, feeding a Common Pool governed by [Conviction Voting](https://forum.tecommons.org/t/conviction-voting-tl-dr/308) (CV), with the goal of creating a self-sustaining funding engine for public goods in the token engineering field. + +The system operated on Gnosis Chain from January 2022 to December 2023, then migrated to Optimism, and was [formally voted to shut down on November 4, 2025](https://forum.tecommons.org/t/tec-shutdown-proposal/1520). This document synthesizes on-chain data analysis across five dimensions — conviction voting, treasury flows, mechanism sustainability, ABC market dynamics, and token distribution — to evaluate what worked, what didn't, and why. + +### The Design Thesis + +The TEC's core mechanism loop was elegant in theory: + +``` +New participants buy TEC via ABC + → Entry tribute (%) flows to Common Pool + → Conviction Voting allocates Common Pool to grants + → Grants create value in the TE ecosystem + → Value attracts new participants → cycle repeats +``` + +**The central finding of this analysis is that the feedback loop never achieved self-sustainability.** Tribute inflows consistently fell short of grant outflows, the Common Pool functioned as a drawdown fund rather than a renewable one, and exogenous market shocks (Terra/Luna, FTX) accelerated a decline that the mechanisms were not designed to withstand. + +--- + +## 2. Origins: The Hatch & Commons Upgrade + +The TEC began with a [Hatch](https://forum.tecommons.org/t/the-hatch-tl-dr/272) — a fundraising phase restricted to Trusted Seed members. The [Hatch closed on August 11, 2021](https://medium.com/token-engineering-commons/the-hatch-was-successful-2443cd07cbb0) with **1,571,224 wxDAI raised from 210 backers**. Hatch tokens were initially frozen (non-transferable) while the community collaboratively designed the economic parameters through the [Commons Configuration Dashboard](https://forum.tecommons.org/t/the-commons-configuration-dashboard/573). + +The parameter design process was itself a token engineering exercise: [40 proposals](https://forum.tecommons.org/t/how-do-the-hatch-param-proposals-stack-up/385), two weeks of debate, and two rounds of voting. The community selected parameters for the [Opening Price & Reserve Ratio](https://forum.tecommons.org/t/augmented-bonding-curve-opening-price-reserve-ratio/516), [Entry & Exit Tributes](https://forum.tecommons.org/t/augmented-bonding-curve-entry-exit-tribute/494), the [Commons Tribute](https://forum.tecommons.org/t/augmented-bonding-curve-commons-tribute/517) (hatch fund split), and [Conviction Voting parameters](https://forum.tecommons.org/t/conviction-voting-parameters-general-disccusion/84). + +**Key Parameters as Deployed:** + +| Parameter | Value | Source | +|-----------|-------|--------| +| Reserve Ratio | ~31% | On-chain (Notebook 04) | +| Entry Tribute | ~22% | Whale trade event logs (Notebook 05) | +| Exit Tribute | ~8–12% | Whale trade event logs (Notebook 05) | +| CV Conviction Growth | 7 days | [TEC Handbook](https://token-engineering-commons.gitbook.io/tec-handbook/archive/archived-content/fund-allocation-layer-and-tools/conviction-voting-funding) | +| CV Minimum Conviction | 4% | TEC Handbook | +| CV Spending Limit | 11% per proposal | TEC Handbook | + +The ABC went live on Gnosis Chain in **January 2022**, with the first conviction voting proposal submitted on January 27, 2022. + +--- + +## 3. Conviction Voting: Governance That Worked — Until It Didn't + +### 3.1 Scale and Outcomes + +Over 16 months of active operation (Jan 2022 – May 2023), conviction voting processed **47 proposals**, of which **36 were funded** (84% success rate among real proposals), disbursing a total of **680,295 TEC** from the Common Pool. + +The high success rate suggests proposals were well-vetted before formal submission — a feature of conviction voting's design, where the continuous, time-weighted nature of support accumulation incentivizes pre-submission community alignment. Only 7 proposals were cancelled, and of those, a significant fraction came from beneficiaries who later resubmitted and received funding. + +### 3.2 Spending Categories + +Funded proposals spanned a diverse portfolio: + +| Category | TEC Funded | % of Total | # Proposals | +|----------|-----------|------------|-------------| +| Community & Operations | Largest share | — | Multiple | +| Education (TE Academy) | Significant | — | Multiple | +| Research (cadCAD, etc.) | Moderate | — | Multiple | +| Rewards & Recognition | Moderate | — | Multiple | +| Tooling & Infrastructure | Smaller | — | Fewer | + +*(Detailed breakdown with exact numbers available in Notebook 02, `cv_spending_categories.png`)* + +The TEC's lifetime grants totaled **$433,316 in direct funding** plus an additional **~$250K via Gitcoin** matching rounds. Key beneficiaries included TE Academy, cadCAD development, GravityDAO (conflict resolution), and various research initiatives. + +### 3.3 Participation and Concentration + +**159 unique stakers** participated in conviction voting — approximately **13% of the ~1,200 token holders**. Participation was heavily concentrated: + +- **Gini coefficient: 0.843** (high inequality) +- **Top 10 stakers controlled 65.1%** of total stake +- **69 of 159 stakers (43%)** voted on only one proposal +- Only stakers on 5+ proposals showed sustained engagement + +This concentration wasn't necessarily a flaw — conviction voting's design inherently allows proportional influence by token holdings. But it meant that a small group of committed participants effectively drove allocation decisions, while the vast majority of token holders were passive. + +### 3.4 The Abstain Proposal as Inertial Brake + +The TEC implemented an "Abstain" proposal (#1) as a mechanism for token holders to signal "slow down spending" without opposing specific proposals. Tokens staked on Abstain reduced the effective conviction available for all other proposals, functioning as an [inertial brake on governance throughput](https://forum.tecommons.org/t/strengths-and-weaknesses-of-conviction-voting-and-other-mechanisms/1278). + +**The Abstain proposal accumulated up to 729,141 TEC** in peak stake — often exceeding the combined stake on all active proposals. The "brake strength" (Abstain's share of total staked tokens) averaged roughly 50–70% for much of the system's life, meaning proposals needed to overcome significant inertia to pass. This worked as intended during healthy periods but became problematic as community engagement declined: fewer active voters meant Abstain's inertial dominance grew relative to dwindling active conviction. + +As Gideonro noted in a [forum discussion on CV strengths and weaknesses](https://forum.tecommons.org/t/strengths-and-weaknesses-of-conviction-voting-and-other-mechanisms/1278): "*having conviction build automatically over time does build momentum*" that can drain treasuries, and the Abstain workaround "*created unexpected behavioral problems when voters reallocated tokens after proposals passed.*" + +### 3.5 Conviction Dynamics + +Funded proposals had a **median active lifetime of ~30 days**, with conviction building gradually before crossing the funding threshold. Larger proposals required sustained support over weeks. The 7-day conviction growth parameter (the half-life for conviction accumulation) created a meaningful delay that filtered out impulsive allocation — but also meant urgent funding needs moved slowly. + +The system exhibited a clear lifecycle pattern: high activity in early 2022, steady throughput through mid-2022, then declining participation that correlated with treasury depletion and token price decline. + +--- + +## 4. The Augmented Bonding Curve: Structural Sell Pressure + +### 4.1 The Buy/Sell Asymmetry + +The ABC's most striking empirical feature was **overwhelming structural sell pressure**: + +| Metric | Buys | Sells | +|--------|------|-------| +| Transaction count | 398 | 2,217 | +| Sell:Buy ratio | — | **5.6:1** | +| Total volume | Minority share | Dominant | + +The ABC was used **primarily as an exit mechanism**, not an entry mechanism. This is the opposite of what the design thesis required — the system needed net buying pressure to generate tribute revenue for the Common Pool. + +### 4.2 Price Trajectory + +- **Peak ABC price: 2.94 xDAI** (early 2022) +- **Final ABC price: 0.36 xDAI** (December 2023) +- **Drawdown: -88%** + +The reserve pool declined from a peak of **1,119,156 xDAI to 111,623 xDAI**, with token supply peaking then contracting as sells burned tokens faster than buys minted them. + +### 4.3 Tribute Revenue: Insufficient by Design? + +Total ABC tribute revenue over the full lifecycle: **~329,904 xDAI** + +- Entry tributes (22% of buy volume): generated significant per-transaction revenue but from insufficient volume +- Exit tributes (8–12% of sell volume): captured value from sellers but couldn't offset the drain + +The [entry/exit tribute structure](https://forum.tecommons.org/t/augmented-bonding-curve-entry-exit-tribute/494) faced a fundamental paradox identified early in [forum debates](https://forum.tecommons.org/t/augmented-bonding-curve-commons-tribute/517): high tributes discourage participation, low tributes don't generate enough revenue. The 22% entry tribute was notably aggressive — effectively a tax on joining — which may have suppressed buy-side volume. As one community member [noted during parameter design](https://forum.tecommons.org/t/augmented-bonding-curve-entry-exit-tribute/494), "*a small (but >0%) entry tribute would likely generate more funding for the Common Pool than an extremely high percentage (>15%) because* [high rates] *discourage purchases entirely.*" + +By Q1 2025, quarterly tribute revenue had declined to just **~$3,614** — a fraction of the ~$42,000 quarterly operating expenditure reported in the [Q1 2025 Progress Report](https://forum.tecommons.org/t/tec-q1-2025-progress-report/1472). + +### 4.4 Primary vs. Secondary Market Divergence + +The TEC token traded on both the ABC (Gnosis Chain) and secondary DEXes (Honeyswap on Gnosis, later Velodrome on Optimism). Comparing daily prices: + +- The DEX price frequently traded at a **discount** to the ABC price +- The mean DEX-to-ABC spread was negative, meaning traders could buy cheaper on the DEX than by minting on the ABC +- **26,107 DEX trades** vs. 2,615 ABC trades — the secondary market saw 10x the activity + +This DEX discount created an arbitrage dynamic that further undermined the ABC: rational actors would buy on Honeyswap (cheaper, no entry tribute) rather than minting via the ABC. The ABC's entry tribute effectively priced itself out of its own market. + +### 4.5 The 500K Whale + +The single largest ABC participant — wallet `0xf5dcd98a...12f35497` — made a **499,803 xDAI purchase on January 25, 2022**, representing 46.5% of all ABC buy volume in a single transaction. + +- **Entry tribute paid: ~109,957 xDAI** (22%) +- **TEC received: ~165,000 TEC** +- **Subsequent exits**: 6 sell transactions from May 2022 to June 2023, at declining prices +- **Realized P&L: deeply negative** (sold recovered only a fraction of the investment) +- **Total tribute contribution: ~123,000 xDAI** (entry + exit) + +This single whale contributed roughly **37% of all ABC tribute revenue**. The system's financial sustainability was, to a troubling degree, dependent on a handful of large participants who entered early and whose exits compounded sell pressure. + +### 4.6 Token Holder Concentration + +At the time of analysis: + +- **723 total holders** +- **Top holder (gideonro.eth): 13.2%** of supply +- **Top 10 holders: 50.7%** of supply +- **50% of supply held by just the top ~10 addresses** +- **80% of supply held by the top ~40 addresses** + +Holder count grew initially then plateaued and declined — a pattern consistent with the death spiral hypothesis. + +--- + +## 5. Treasury Dynamics: The Drawdown Fund + +### 5.1 Common Pool Depletion + +The Common Pool — the funding source for conviction voting — followed a steady downward trajectory: + +- **Peak balance: 1,073,976 tokens** +- **Final balance: 0** (fully depleted by December 2023) +- **Total outflows: 1,195,952** (grants + operating costs) +- **17 of 24 months had net negative flows** (outflows exceeded inflows) + +The fundamental coverage ratio — total inflows divided by total outflows — was well below 1.0x. The Common Pool was never self-sustaining. + +### 5.2 Reserve Pool + +The Reserve Pool (ABC collateral) tracked the broader market: + +- **Peak: 1,119,096 xDAI** +- **Final: ~0** (drained through ABC sells) + +The reserve ratio drifted from its ~31% target as sell pressure eroded collateral faster than the bonding curve formula could adjust. + +### 5.3 Post-Migration (Optimism Era) + +After [migrating to Optimism in December 2023](https://forum.tecommons.org/t/and-we-are-live-on-op-mainnet/1324), the TEC shifted from conviction voting to manual treasury allocations via a coordination team multisig. The reserve currency changed from xDAI to rETH. + +**Post-migration treasury:** +- **Peak value: ~$348,595** +- **Value at analysis end: ~$208,710** +- **Holdings**: DAI, TEC, and rETH +- **Drawdown from peak: significant**, driven by discrete spending events and market movements + +By the [Q1 2025 Progress Report](https://forum.tecommons.org/t/tec-q1-2025-progress-report/1472), total assets stood at ~$300,366 — with quarterly expenditures of $42,244 against only $3,614 in ABC tribute revenue. + +--- + +## 6. The Death Spiral: Correlated Decline + +Plotting the normalized trajectories of reserve pool balance, common pool balance, and governance activity reveals a tightly correlated decline — the classic "death spiral" pattern: + +1. **Token price drops** → less attractive to hold +2. **Holders sell via ABC** → reserve pool shrinks → price drops further +3. **Less ABC activity** → less tribute revenue → common pool depletes faster +4. **Less funding available** → fewer proposals → less community activity +5. **Less activity** → holders leave → cycle repeats + +Two exogenous shocks accelerated the spiral: +- **Terra/Luna collapse (May 2022)**: broad crypto market downturn +- **FTX collapse (November 2022)**: deepened the crypto winter + +But the structural problem predated these shocks. The ABC's sell pressure was 5.6:1 from the start. The Common Pool was net-negative in 17 of 24 months. The feedback loop required continuous external demand that never materialized at sufficient scale. + +--- + +## 7. Mechanism Design Scorecard + +### Augmented Bonding Curve + +| Criterion | Assessment | +|-----------|------------| +| Continuous fundraising | **Partial** — raised capital initially but became primarily an exit mechanism | +| Price floor / support | **Failed** — 88% drawdown; reserve depleted | +| Tribute revenue generation | **Insufficient** — 329K xDAI lifetime, declining to ~$3.6K/quarter | +| Market making | **Undermined** — secondary DEX offered cheaper entry, bypassing tributes | + +### Conviction Voting + +| Criterion | Assessment | +|-----------|------------| +| Fund allocation | **Succeeded** — 36 proposals funded across diverse categories | +| Sybil resistance | **Succeeded** — time-weighted conviction made gaming expensive | +| Broad participation | **Partial** — 159 of ~1,200 holders (13%); Gini 0.843 | +| Sustainability signaling | **Partial** — Abstain mechanism worked but couldn't prevent depletion | + +### The Feedback Loop + +| Criterion | Assessment | +|-----------|------------| +| Self-sustainability | **Failed** — Common Pool never renewable | +| Value creation | **Succeeded** — $433K in grants + $250K via Gitcoin funded real work | +| Growth flywheel | **Failed** — value created didn't translate to ABC buying pressure | + +--- + +## 8. What Broke Down — And What Worked + +### What didn't work + +1. **The tribute model required perpetual growth.** ABC tributes can only sustain a Common Pool if buy-side volume persistently exceeds grant outflows. In a bear market with no external revenue, the pool inevitably depletes. + +2. **High entry tribute (22%) suppressed buying.** Combined with DEX availability offering cheaper TEC, the ABC became unattractive as an entry point. Rational participants bought on Honeyswap and sold on the ABC — the reverse of the intended flow. + +3. **No external revenue mechanism.** The entire system depended on trading activity for revenue. When trading declined, revenue collapsed. There was no fee-generating product, no staking yield, no service income — only tributes on a shrinking volume base. + +4. **Governance participation concentrated and declined.** With only 13% of holders actively governing, the system was vulnerable to whale exit or disengagement. When the token price fell, the opportunity cost of holding TEC for governance rose, and participation waned. + +### What worked + +1. **Conviction Voting delivered on its core promise.** The mechanism allocated $433K+ to real projects — TE Academy, cadCAD, Gravity, research — that created genuine value. The 84% success rate and diverse portfolio suggest the allocation mechanism worked well within its constraints. + +2. **The Abstain mechanism was a genuine innovation.** It provided a continuous, non-binary signal for governance pace — something binary voting systems lack. Its interaction with conviction dynamics deserves further study. + +3. **Collaborative parameter design was a token engineering achievement.** The Hatch → Commons Configuration → Commons Upgrade pipeline demonstrated that communities can collaboratively design and deploy complex economic systems. The [Commons Configuration Dashboard](https://forum.tecommons.org/t/the-commons-configuration-dashboard/573) process was itself a contribution to the field. + +4. **Graceful shutdown.** As mzargham commented on the [shutdown proposal](https://forum.tecommons.org/t/tec-shutdown-proposal/1520): "*The ability to design and execute a graceful shutdown process is a testament to a life well lived.*" The TEC's orderly wind-down — with [severance for coordinators, a $10K retrospective research grant, knowledge archival](https://forum.tecommons.org/t/tec-shutdown-proposal/1520), and pro-rata distribution to holders — is a model for responsible DAO sunsetting. + +--- + +## 9. Implications for Future Mechanism Design + +### For Bonding Curves + +- **Entry tributes above ~5% create perverse incentives** when secondary markets exist. The DEX becomes the rational entry point, starving the ABC of tribute revenue. +- **Reserve ratios must account for sustained sell pressure.** A 31% ratio provided insufficient buffer against the 5.6:1 sell:buy dynamics that emerged. +- **ABCs work for initial capitalization but not ongoing funding** unless buy-side demand is structurally guaranteed (e.g., by utility that requires token purchase). + +### For Conviction Voting + +- **CV needs a replenishing pool.** As [discussed on the forum](https://forum.tecommons.org/t/strengths-and-weaknesses-of-conviction-voting-and-other-mechanisms/1278), CV exhibits "a built-in bias for passing funding proposals" and functions best with abundant, renewable funding — not a fixed endowment. +- **The Abstain mechanism needs refinement.** Its behavioral interactions with proposal lifecycle events (reallocation after proposal execution) created unexpected dynamics. +- **13% participation may be structurally inherent** in token-weighted governance without delegation or incentives for participation. + +### For DAO Sustainability + +- **Trading-fee-dependent funding models are fragile.** Revenue must come from sources less correlated with market sentiment — services, subscriptions, protocol fees, or diversified treasuries. +- **The "growth flywheel" assumption is the critical risk.** If funded projects don't generate measurable token demand, the loop breaks regardless of mechanism design quality. +- **Plan for shutdown.** The TEC's experience suggests every DAO should design its end-of-life process alongside its governance — not as an afterthought. + +--- + +## 10. Data Sources & Methods + +All analysis is based on on-chain data and publicly available forum records: + +- **ABC trades, reserve, and supply**: [Dune Analytics TEC Dashboard](https://dune.com/tec/tec) — 2,615 detailed ABC trades, 32,000 expanded trade records +- **DEX trades**: Dune queries covering 26,107 Honeyswap and Velodrome trades (Jan 2022 – Mar 2026) +- **Conviction Voting**: Gardens subgraph data — 47 proposals, 891 stake events, 873 support updates +- **Treasury pools**: Dune pool balance exports — 871 common pool and 886 reserve pool daily records +- **Token holders**: Dune holder snapshots — 723 addresses with balances and concentration metrics +- **Post-migration balances**: Dune token balance tracking (Dec 2023 – Dec 2025) +- **Whale analysis**: Direct Gnosis Chain RPC event log decoding for wallet `0xf5dcd98a...` +- **Forum context**: TEC Forum at [forum.tecommons.org](https://forum.tecommons.org/) + +Contract addresses (Gnosis Chain): +- TEC Token: `0x5dF8339c5E282ee48c0c7cE8A7d01a73D38B3B27` +- ABC: `0x74ade20c12067e2f9457c037809a73f35694f99f` +- Common Pool: `0xb941365430a16659658bb23b88efaede1d839354` + +Analysis notebooks and raw data available in the [TEC-analysis repository](https://github.com/jeffemmett/TEC-analysis). + +--- + +## Key Forum References + +| Topic | Link | +|-------|------| +| Shutdown Proposal (passed Nov 4, 2025) | [forum.tecommons.org/t/tec-shutdown-proposal/1520](https://forum.tecommons.org/t/tec-shutdown-proposal/1520) | +| Sunsetting & Treasury Distribution | [forum.tecommons.org/t/sunsetting-the-tec-proposal-treasury-distribution-framework/1500](https://forum.tecommons.org/t/sunsetting-the-tec-proposal-treasury-distribution-framework/1500) | +| Q1 2025 Progress Report | [forum.tecommons.org/t/tec-q1-2025-progress-report/1472](https://forum.tecommons.org/t/tec-q1-2025-progress-report/1472) | +| Dune Dashboard 2024 | [forum.tecommons.org/t/dune-tec-dashboard-2024/1371](https://forum.tecommons.org/t/dune-tec-dashboard-2024/1371) | +| Strengths & Weaknesses of CV | [forum.tecommons.org/t/strengths-and-weaknesses-of-conviction-voting/1278](https://forum.tecommons.org/t/strengths-and-weaknesses-of-conviction-voting-and-other-mechanisms/1278) | +| ABC Introduction | [forum.tecommons.org/t/augmented-bonding-curve-an-introduction-to-the-abc/497](https://forum.tecommons.org/t/augmented-bonding-curve-an-introduction-to-the-abc/497) | +| Entry & Exit Tribute Parameters | [forum.tecommons.org/t/augmented-bonding-curve-entry-exit-tribute/494](https://forum.tecommons.org/t/augmented-bonding-curve-entry-exit-tribute/494) | +| Opening Price & Reserve Ratio | [forum.tecommons.org/t/augmented-bonding-curve-opening-price-reserve-ratio/516](https://forum.tecommons.org/t/augmented-bonding-curve-opening-price-reserve-ratio/516) | +| Conviction Voting Parameters | [forum.tecommons.org/t/conviction-voting-parameters-general-disccusion/84](https://forum.tecommons.org/t/conviction-voting-parameters-general-disccusion/84) | +| Half-Life Deep Dive | [forum.tecommons.org/t/half-life-conviction-voting-deep-dive/160](https://forum.tecommons.org/t/half-life-conviction-voting-deep-dive/160) | +| Minimum Conviction Threshold | [forum.tecommons.org/t/conviction-voting-minimum-conviction-aka-minimum-threshold/493](https://forum.tecommons.org/t/conviction-voting-minimum-conviction-aka-minimum-threshold/493) | +| Commons Configuration Dashboard | [forum.tecommons.org/t/the-commons-configuration-dashboard/573](https://forum.tecommons.org/t/the-commons-configuration-dashboard/573) | +| Hatch Parameters Discussion | [forum.tecommons.org/t/hatch-parameters-general-discussion-thread/61](https://forum.tecommons.org/t/hatch-parameters-general-discussion-thread/61) | +| Hatch TL;DR | [forum.tecommons.org/t/the-hatch-tl-dr/272](https://forum.tecommons.org/t/the-hatch-tl-dr/272) | +| Migration to Optimism (Simulation) | [forum.tecommons.org/t/simulating-the-tec-migration-to-optimism/1319](https://forum.tecommons.org/t/simulating-the-tec-migration-to-optimism/1319) | +| Live on OP Mainnet | [forum.tecommons.org/t/and-we-are-live-on-op-mainnet/1324](https://forum.tecommons.org/t/and-we-are-live-on-op-mainnet/1324) | +| Commons Upgrade Proposals | [Hatch Proposals Stack-up](https://forum.tecommons.org/t/how-do-the-hatch-param-proposals-stack-up/385) | + +--- + +*This analysis was conducted as part of the [Bonding Curve Research Group retrospective](https://forum.tecommons.org/t/tec-shutdown-proposal/1520), funded by the TEC shutdown allocation. Data collection and visualization notebooks are available at `notebooks/01–05` in the project repository.* diff --git a/scripts/gen_timeline.py b/scripts/gen_timeline.py new file mode 100644 index 0000000..0e8e8d8 --- /dev/null +++ b/scripts/gen_timeline.py @@ -0,0 +1,138 @@ +"""Generate a Markwhen timeline (.mw) for the TEC retrospective. + +Inputs: + data/onchain/cv_proposals.csv (id, block, amount_requested, link, status, executed_block) + data/onchain/cv_proposal_categories.json (id -> category tag, optional) + +Output: + output/tec_retrospective.mw + +Anchoring: Gnosis block 20086948 == 2022-01-27 (CV proposal #1 per synthesis), +block time ~5.0s. Close enough for a retrospective timeline. +""" +from __future__ import annotations + +import csv +import json +from datetime import datetime, timedelta, timezone +from pathlib import Path + +ROOT = Path(__file__).resolve().parent.parent +PROPOSALS = ROOT / "data" / "onchain" / "cv_proposals.csv" +CATEGORIES = ROOT / "data" / "onchain" / "cv_proposal_categories.json" +OUT = ROOT / "output" / "tec_retrospective.mw" + +ANCHOR_BLOCK = 20086948 +ANCHOR_DATE = datetime(2022, 1, 27, tzinfo=timezone.utc) +GNOSIS_BLOCK_SECONDS = 5.0 + + +def block_to_date(block: int) -> datetime: + delta = (block - ANCHOR_BLOCK) * GNOSIS_BLOCK_SECONDS + return ANCHOR_DATE + timedelta(seconds=delta) + + +def load_categories() -> dict[str, str]: + if not CATEGORIES.exists(): + return {} + raw = json.loads(CATEGORIES.read_text()) + if isinstance(raw, dict): + return {str(k): str(v) for k, v in raw.items()} + return {} + + +HEADER = """--- +title: Token Engineering Commons — Retrospective +view: timeline +timezone: UTC +#hatch: blue +#abc: orange +#cv: green +#shock: red +#migration: purple +#shutdown: gray +--- + +// Generated by scripts/gen_timeline.py +// Edit macro events here; CV proposal section is auto-appended. + +section Origins #hatch +2021-02-01 / 2021-08-11: Trusted Seed recruitment & Hatch prep + 210 backers onboarded via Commons Stack Hatch app +2021-08-11: Hatch closed — 1,571,224 wxDAI raised from 210 backers #hatch + https://medium.com/token-engineering-commons/the-hatch-was-successful-2443cd07cbb0 +2021-08-12 / 2022-01-26: Commons Configuration Dashboard — 40 parameter proposals, 2 rounds of voting #hatch +endSection + +section ABC & Markets #abc +2022-01-25: 500K whale purchase — 499,803 xDAI (46.5% of all ABC buy volume, ever) #abc + wallet 0xf5dcd98a...12f35497 · entry tribute ~109,957 xDAI +2022-01-27: ABC live on Gnosis Chain; first CV proposal submitted #abc #cv +2022-05-09: Terra/Luna collapse — first exogenous shock #shock +2022-11-08: FTX collapse — second exogenous shock, crypto winter deepens #shock +2023-12-01: ABC price bottom — 0.36 xDAI (-88% from peak of 2.94) #abc +endSection + +section Treasury & Migration #migration +2023-12-15: Migration to Optimism; CV replaced by multisig coordination #migration + reserve currency: xDAI → rETH + https://forum.tecommons.org/t/and-we-are-live-on-op-mainnet/1324 +2024-01-01 / 2025-11-04: Post-migration draw-down era (manual allocations) +2025-04-01: Q1 2025 Progress Report — tribute revenue $3,614/qtr vs $42,244/qtr opex #shutdown + https://forum.tecommons.org/t/tec-q1-2025-progress-report/1472 +2025-11-04: TEC shutdown proposal formally approved #shutdown + https://forum.tecommons.org/t/tec-shutdown-proposal/1520 +endSection + +""" + + +def build_cv_section(rows: list[dict], cats: dict[str, str]) -> str: + lines = ["section Conviction Voting Proposals #cv", ""] + for row in rows: + pid = row["id"] + try: + block = int(row["block"]) + except (TypeError, ValueError): + continue + created = block_to_date(block) + executed = None + if row.get("executed_block"): + try: + executed = block_to_date(int(row["executed_block"])) + except ValueError: + pass + amount = row.get("amount_requested") or "0" + try: + amount_f = float(amount) + except ValueError: + amount_f = 0.0 + status = (row.get("status") or "").lower() + title = (row.get("link") or f"Proposal #{pid}").strip() or f"Proposal #{pid}" + title = title.replace("\n", " ")[:90] + cat = cats.get(str(pid), "") + tags = [f"#{status}"] if status else [] + if cat: + tags.append(f"#{cat.lower().replace(' ', '_')}") + tag_str = " " + " ".join(tags) if tags else "" + if executed and status == "executed": + rng = f"{created:%Y-%m-%d} / {executed:%Y-%m-%d}" + else: + rng = f"{created:%Y-%m-%d}" + amount_note = f" — {amount_f:,.0f} TEC" if amount_f > 0 else "" + lines.append(f"{rng}: #{pid} {title}{amount_note}{tag_str}") + lines.append("endSection") + return "\n".join(lines) + "\n" + + +def main() -> None: + rows = list(csv.DictReader(PROPOSALS.open())) + cats = load_categories() + body = HEADER + build_cv_section(rows, cats) + OUT.parent.mkdir(exist_ok=True) + OUT.write_text(body) + print(f"Wrote {OUT} ({len(rows)} proposals)") + + +if __name__ == "__main__": + main()