From 84a3e427b4afc567281624b3aaf902a3c13935f4 Mon Sep 17 00:00:00 2001 From: Jeff Emmett Date: Fri, 3 Apr 2026 12:20:46 -0700 Subject: [PATCH] Initial repo structure for TEC token dynamics analysis Sets up project skeleton for analyzing the Token Engineering Commons augmented bonding curve, conviction voting, and primary/secondary market dynamics. Co-Authored-By: Claude Opus 4.6 --- .gitignore | 28 +++++++++++++++++ README.md | 54 +++++++++++++++++++++++++++++++++ data/offchain/.gitkeep | 0 data/onchain/.gitkeep | 0 data/snapshots/.gitkeep | 0 references/data-sources.md | 61 ++++++++++++++++++++++++++++++++++++++ requirements.txt | 11 +++++++ 7 files changed, 154 insertions(+) create mode 100644 .gitignore create mode 100644 README.md create mode 100644 data/offchain/.gitkeep create mode 100644 data/onchain/.gitkeep create mode 100644 data/snapshots/.gitkeep create mode 100644 references/data-sources.md create mode 100644 requirements.txt diff --git a/.gitignore b/.gitignore new file mode 100644 index 0000000..8d9f6f2 --- /dev/null +++ b/.gitignore @@ -0,0 +1,28 @@ +# Python +__pycache__/ +*.py[cod] +*.egg-info/ +.venv/ +venv/ + +# Jupyter +.ipynb_checkpoints/ + +# Data (large files) +data/onchain/*.csv +data/onchain/*.json +data/offchain/*.csv +data/snapshots/*.csv +!data/**/.gitkeep + +# Environment +.env +.env.local + +# IDE +.vscode/ +.idea/ + +# OS +.DS_Store +Thumbs.db diff --git a/README.md b/README.md new file mode 100644 index 0000000..231cce5 --- /dev/null +++ b/README.md @@ -0,0 +1,54 @@ +# TEC Analysis + +Analysis of the Token Engineering Commons (TEC) token dynamics, focusing on: + +- **Augmented Bonding Curve (ABC)** — primary market pricing, reserve ratio mechanics, entry/exit tribute +- **Conviction Voting** — proposal funding, signal dynamics, effective supply +- **Primary vs Secondary Market** — price divergence, arbitrage flows, liquidity depth +- **Token Distribution & Governance** — holder concentration, voting power, delegation patterns + +## Structure + +``` +TEC-analysis/ +├── data/ +│ ├── onchain/ # On-chain data exports (ABC txns, CV proposals, token transfers) +│ ├── offchain/ # Off-chain data (forum posts, governance metadata) +│ └── snapshots/ # Point-in-time snapshots of key metrics +├── notebooks/ # Jupyter analysis notebooks +├── src/ +│ ├── abc/ # Augmented Bonding Curve models & analysis +│ ├── conviction_voting/ # Conviction Voting analysis +│ ├── liquidity/ # Liquidity & market structure analysis +│ └── utils/ # Shared data fetching, plotting, helpers +├── docs/ # Write-ups, methodology notes +└── references/ # Papers, specs, prior work +``` + +## Key Questions + +1. **ABC Mechanics**: How has the bonding curve price tracked vs secondary market (Uniswap/Honeyswap)? What's the effective reserve ratio over time? +2. **Entry/Exit Tribute**: How much value has flowed through tributes? Impact on buy/sell asymmetry? +3. **Conviction Voting Dynamics**: How does token lockup in CV affect circulating supply and price? What's the effective participation rate? +4. **Liquidity Fragmentation**: How deep is liquidity across primary (ABC) vs secondary markets? Where do large trades actually execute? +5. **Price Discovery**: Which market leads price discovery — the bonding curve or secondary DEXes? +6. **Governance Concentration**: How concentrated is voting power? Do whales dominate proposal outcomes? + +## Related Local Repos + +- `conviction/` — ABC simulations & cadCAD conviction voting models +- `Aragon_Conviction_Voting/` — Algorithm overview & models +- `conviction-voting-cadcad/` — cadCAD simulation framework +- `myco-bonding-curve/` — Bonding curve parameter sweeps & dashboards + +## Data Sources + +_To be populated — see below for what's needed._ + +## Setup + +```bash +python -m venv .venv +source .venv/bin/activate +pip install -r requirements.txt +``` diff --git a/data/offchain/.gitkeep b/data/offchain/.gitkeep new file mode 100644 index 0000000..e69de29 diff --git a/data/onchain/.gitkeep b/data/onchain/.gitkeep new file mode 100644 index 0000000..e69de29 diff --git a/data/snapshots/.gitkeep b/data/snapshots/.gitkeep new file mode 100644 index 0000000..e69de29 diff --git a/references/data-sources.md b/references/data-sources.md new file mode 100644 index 0000000..5de79e6 --- /dev/null +++ b/references/data-sources.md @@ -0,0 +1,61 @@ +# TEC Data Sources & References + +## CommonsBuild GitHub Repos (Key) + +### Core ABC & Bonding Curve +- **[augmented-bonding-curve-model](https://github.com/CommonsBuild/augmented-bonding-curve-model)** — Python model of the ABC (Bancor formula based) +- **[tec-abc-subgraph](https://github.com/CommonsBuild/tec-abc-subgraph)** — Hosted subgraph for ABC on-chain data +- **[tec-abc-dashboard](https://github.com/CommonsBuild/tec-abc-dashboard)** — ABC dashboard / token converter UI +- **[tec-swap](https://github.com/CommonsBuild/tec-swap)** — Mint/burn TEC tokens interface +- **[FundraisingModel](https://github.com/CommonsBuild/FundraisingModel)** — Token engineering model of the Bancor Formula +- **[Token-Log-Hatch-Params](https://github.com/CommonsBuild/Token-Log-Hatch-Params)** — Community parameterization tool + +### Conviction Voting & Governance +- **[commons-config-dashboard](https://github.com/CommonsBuild/commons-config-dashboard)** — Parameter configuration dashboard +- **[commons-config-backend](https://github.com/CommonsBuild/commons-config-backend)** — Backend for config proposals +- **[commons-config-proposals](https://github.com/CommonsBuild/commons-config-proposals)** — Governance proposals + +### Rewards & Distribution +- **[tec-rewards](https://github.com/CommonsBuild/tec-rewards)** — Rewards analysis (Jupyter notebooks) +- **[rad-classic](https://github.com/CommonsBuild/rad-classic)** — Rewards Analysis Dashboard +- **[tec-census](https://github.com/CommonsBuild/tec-census)** — TEC holder census (balances, contract detection) +- **[praiseanalysis](https://github.com/CommonsBuild/praiseanalysis)** — Praise system analysis + +### Shutdown/Sunset (Recent) +- **[tec-shutdown](https://github.com/CommonsBuild/tec-shutdown)** — Shutdown contracts (Solidity) +- **[TECredeem](https://github.com/CommonsBuild/TECredeem)** — Token redemption interface +- **[TECsunsetcomingsoon](https://github.com/CommonsBuild/TECsunsetcomingsoon)** — Sunset announcement + +## On-Chain Data Sources + +### Gnosis Chain (formerly xDai) +- TEC Token contract: _TBD — need contract address_ +- ABC / Bancor curve contract: _TBD_ +- Conviction Voting (Gardens) contract: _TBD_ +- Block explorer: https://gnosisscan.io/ + +### Subgraphs +- TEC ABC Subgraph (from `tec-abc-subgraph` repo) +- Gardens subgraph (1Hive): _TBD_ + +### DEX / Secondary Market +- Honeyswap (1Hive DEX on Gnosis Chain): TEC/xDAI pair +- Any Uniswap/Sushiswap pairs (if bridged to mainnet) + +## Off-Chain Data Sources +- TEC Forum: https://forum.tecommons.org/ +- Snapshot voting: _TBD_ +- Discord governance discussions +- Medium articles / blog posts + +## Local Related Repos +- `/home/jeffe/Github/conviction/` — ABC simulations, cadCAD conviction voting models +- `/home/jeffe/Github/Aragon_Conviction_Voting/` — Algorithm overview & models +- `/home/jeffe/Github/conviction-voting-cadcad/` — cadCAD simulation framework +- `/home/jeffe/Github/myco-bonding-curve/` — Bonding curve parameter sweeps & dashboards + +## Key Papers & Specs +- Bancor Protocol whitepaper +- Conviction Voting paper (BlockScience) +- Commons Stack ABC specification +- _Add more as identified_ diff --git a/requirements.txt b/requirements.txt new file mode 100644 index 0000000..cc07eeb --- /dev/null +++ b/requirements.txt @@ -0,0 +1,11 @@ +jupyter>=1.0 +pandas>=2.0 +numpy>=1.24 +matplotlib>=3.7 +seaborn>=0.12 +plotly>=5.15 +web3>=6.0 +requests>=2.31 +python-dotenv>=1.0 +scipy>=1.11 +networkx>=3.1