A Research-Grade Framework for Genetic Classification of Tokenomics, On-Chain Behavior, and Smart Contract Economic Structures
Smart contract tokens, especially ERC-20 derivatives, have evolved from simple fixed-supply assets to complex economic organisms with dynamic behavior, intricate control structures, embedded incentive systems, and sometimes malicious intent. The token ecosystem contains thousands of mutations, forks, adaptations, and design patterns.
The Token Genome Project (TGP) introduces a new analytical paradigm:
Treat each token as an organism, and extract its "genetic" code.
These “genes” are not biological; they are behavioral, economic, and structural features that define what a token can do, is allowed to do, or is capable of becoming.
This README explains:
- the theory behind token genomics
- why genes matter
- how the classification system is constructed
- what risk tells us about "organism fitness"
- how TGP extracts genetic traits
- how to extend the taxonomy
- how to use the tool effectively
- the broader implications for DeFi, auditing, and research
This is not just a tool. It is a new lens.
token-genome-project/
│
├── tgp/
│ ├── cli.py # unified scan + compare CLI
│ ├── extractor.py # genome inference engine
│ ├── genes.py # gene definitions + metadata
│ ├── loader.py # Solidity loader
│ ├── models.py # Genome & Gene models
│ ├── risk.py # scoring engine
│ ├── report.py # HTML report generator
│
├── examples/ # curated token examples
│ ├── simple_token.sol
│ ├── unlimited_mint_token.sol
│ ├── capped_mint_token.sol
│ ├── blacklist_tax.sol
│ ├── rebase_token.sol
│ ├── … etc
│
├── genomes/ # generated JSON/HTML outputs (auto-created)
│
├── README.md
└── pyproject.toml
Token codebases mutate and fork:
- ERC-20 → Reflection Tokens (e.g., SafeMoon species)
- ERC-20 → Tax Tokens → honeypot variants
- ERC-20 → Rebase species (OHM forks, AMPL forks)
- ERC-20 → Proxy mutating species (upgradeable, UUPS)
- ERC-20 → Algorithmic stablecoin species
- ERC-20 → Anti-whale / Anti-bot species
- ERC-20 → Blacklist-regulated governance species
These are not just code differences, they are predictable evolutionary branches.
A "gene" is a binary/categorical feature that influences economic behavior.
Examples:
- MINT_UNBOUNDED → infinite inflation potential
- FEE_DYNAMIC → admin can alter financial properties after launch
- BLACKLIST_PRESENT → admin can selectively disable trading
- HONEYPOT_LIKE → potential buy-allow / sell-block
- PROXY_UPGRADEABLE → token can mutate in the future
- MANUAL_PRICE_SETTER → admin manually defines price values
- CENTRALIZATION_RISK_HIGH → excessive admin privileges
These traits directly correspond to real-world behaviors.
This approach answers questions like:
- What species does this token belong to?
- What class of risks does it inherently carry?
- How similar are token A and token B?
- Which features evolved first?
- Are dangerous mutations emerging?
- What behavioral patterns dominate new launches?
To make genomics systematic, TGP uses formal definitions:
A mapping of gene → boolean/number.
A detectable feature with:
- key
- category
- description
- (optional) weight
- (optional) risk contribution
Genes are grouped by logical taxonomy:
| Category | Meaning |
|---|---|
| monetary_policy | supply, inflation, burn, rebase |
| fees | taxes, reflections, adjustable fees |
| permissions | ownership, blacklist, whitelist |
| liquidity | honeypot behavior, LP control |
| oracle | price manipulation vectors |
| upgradeability | proxy mutation potential |
| risk | centralization, admin power |
Aggregated gene-weight metric representing "dangerous potential".
Informal classification (future ML clustering). Examples:
- Tax Predator Species
- Rebase Species
- Proxy Mutant Species
- Oracle-Controlled Species
- Blacklist-Regulated Species
- Infinite-Mint Species
- Legitimate Simple Species
TGP uses heuristic static analysis:
The extractor scans for patterns like:
mint(setFee(setBlacklist(renounceOwnershipdelegatecall/implementation_transfer(logic complexityprice =orsetPrice()rebase()- fee/tax keywords (
fee,tax,reflection,redistribute)
Detect EOA-like owner patterns:
- OpenZeppelin Ownable
- custom onlyOwner patterns
- multiple owner-gated functions
- renounceOwnership logic
This determines centralization genes.
The tool detects:
- selective transfer control
- dynamic fee switching
- trading toggles
- blacklists/whitelists
- admin drain functions
- kill-switches
- LP unlockers
Proxy detection:
- presence of implementation storage
- delegatecall
- upgrade function
- admin-only upgrade logic
Below is a detailed breakdown of each gene category.
Indicates the token has minting without a supply cap.
Risks:
- Admin can inflate supply infinitely.
- Price can be destroyed instantly.
- Perfect rug-pull tool.
Found in: Scams, rug tokens, "infinite mint predators".
Minting exists but is bound by a max supply or cap variable.
Interpretation: Potentially trustworthy but needs scrutiny.
Token can reduce supply via user burn.
Interpretation: Neutral. Sometimes used for deflationary models.
Supply adjusts algorithmically (positive or negative).
Implications:
- Price and supply correlate inversely.
- Balances may change automatically.
- Not suitable for regular wallets.
- Associated with AMPL/OHM forks.
Simple tax or transfer fee.
Admin can modify fee levels.
Interpretation:
- Useful for treasury protocols
- Dangerous for scams (admin -> 100% fee)
Combination of:
- fee-based tokenomics
- owner control
- tax functions
- often seen in honeypots
Meaning: This token is structurally similar to known scams.
Single externally-owned account has high privileges.
Risk: If compromised = total compromise.
Admin can disable trading for specific addresses.
Interpretation: Often used in:
- honeypots
- rug tokens
- censorship-based control tokens
Trading is allowed only for approved addresses.
Used by:
- presale tokens
- launchpad tokens
- early-stage scams to block sells
Admin can globally pause/unpause trading.
High control gene.
Combined conditions:
- blacklist present
- trading toggle
- fees = strong pattern for buy-allowed / sell-blocked scams.
This is a dangerous gene.
Admin can set price manually.
Dangers:
- price manipulation
- liquidation manipulation
- front-running attackers
- stablecoin depegs by admin decision
Token can mutate after deployment.
Risk spectrum:
- legitimate upgradable tokens (safe)
- malicious upgrade scripts (rug potential)
Context determines interpretation.
Fires when:
- many admin-only functions
- dynamic powers
- mint + fee control
- oracles + price control
Meaning: The admin is the "god mode" of the token.
TGP uses a weighted score. Weights are based on:
- historical exploit patterns
- audit findings in real world
- typical scam strategies
- DeFi economic behavior
Weights approximate:
Minor centralization but no severe vectors.
Some dangerous patterns, but not fatal.
Multiple vectors combine to form a real threat.
This is a ticking time bomb.
Each report includes:
Token, risk level, score.
For each gene:
- Name
- Category
- Risk Weight
- Description
Planned features:
- Narrative summary
- Risk explanation paragraphs
- Power mapping (ownership/lp/oracle)
tgp-scan examples
This:
- loads all
.solfiles - runs gene extractor
- computes risk
- saves genome JSON
- saves HTML reports
- prints human-readable summary
tgp-scan --mode compare tokenA.sol --other tokenB.sol
This prints:
- shared active genes
- genes unique to A
- genes unique to B
- structural and economic differences
Useful for:
- mutation detection
- fork analysis
- audit differential review
- identifying scam clones
Given:
=== unlimited_mint_token.sol ===
Risk: HIGH (score=10)
MINT_UNBOUNDED ACTIVE Mint without cap
OWNER_EOA_LIKE ACTIVE EOA-like owner control
Meaning:
-
MINT_UNBOUNDED admin can create infinite supply → inflation risk + rug capability.
-
OWNER_EOA_LIKE one person controls the entire token.
-
HIGH score = → token belongs to “Infinite Mint Predator” species. → not suitable for public trading.
tgp-scan --mode compare unlimited_mint.sol --other capped_mint.sol
Output:
Shared active genes:
OWNER_EOA_LIKE
Active only in unlimited_mint:
MINT_UNBOUNDED
Active only in capped_mint:
MINT_CAPPED
Interpretation:
- Both tokens are centrally controlled (bad).
- One has unlimited inflation (very bad).
- One has capped inflation (acceptable).
You can add new genes easily in tgp/genes.py.
Potential expansions:
- LIQUIDITY_LOCKED
- LIQUIDITY_UNLOCKABLE
- AUTO_LP_ADD
- REMOVE_LP_ADMIN
- ANTI_WHALE
- COOL_DOWN
- MAX_SELL_TOKENS
- TOKEN_VOTING
- TIMELOCK_CONTROLLER
- PAUSABLE_GOV
- RUG_DRAIN_VECTOR
- PRICE_MANIPULATION_VECTOR
This can grow into a 200+ gene ecosystem.
Use clustering to identify:
- evolutionary branches
- signatures of scam evolution
- decentralized vs. centralized species groups
- tokenomic hybrid models
Construct token evolution trees similar to biological genealogy.
Analyze which features drift over time in DeFi cycles.
During bull markets, certain genes dominate (reflection, tax). During bear markets, others dominate (rebase, stablecoins).
Detect outlier behavior patterns.
Train models to classify scam species using genetic vectors.
- Allows scientific understanding of token ecosystems.
- Helps auditors detect malicious behavior fast.
- Helps researchers map tokenomic evolution.
- Helps analysts compare forks.
- Helps developers avoid dangerous patterns.
- Helps the community identify rug-pull species.
The Token Genome Project is the first step toward systematic cryptoeconomic taxonomy.
This project treats tokenomics as a living ecosystem. Each contract is a creature. Each feature is a gene. Each combination is a species.
TGP gives you tools to map, classify, evaluate, and compare those organisms.
The deeper you go, the more insights you uncover.