blockchainlab-index

A machine-readable code index of the curated Blockchains forks. It is built from shallow clones of the fork source, not from READMEs. The Blockchain Lab /forge composer uses it to turn a plain-language idea into a working project. Rebuilt nightly at 03:41 UTC, after fork-sync runs.

Layout

Path	What
catalog.json	One record per repo: fork, upstream, pinned commit, licence, stars, VM/standard tags, packages, install commands, component counts, file URLs
components/<slug>.json	Every production contract, module, circuit, program and Go package. Each entry has its path, kind, functions/events/errors, SPDX licence, pragma, rule-based and semantic capability tags, and a raw URL at the pinned commit
vectors/<slug>.i8	Per-component embeddings: BLV1 header, then int8 rows. BAAI/bge-small-en-v1.5, 384 dimensions, CLS pooling, L2-normalised, scale 127
search/components-NNN.json, search/symbols-<c>.json	Static search shards for browsers (component and symbol lookup)
index.sqlite	SQLite with FTS5 over components and symbols, for server-side search
taxonomy/capabilities.json	Capability taxonomy: id, synonyms, standards, VM, match rules, preferred components, licence policy
taxonomy/reuse.json	How to reuse forks as building blocks: install methods plus a note per category. Each catalog.json repo also has a reuse field (method, pin, pinned install lines, notes, license_note), generated by indexer/reuse.py
repos/<slug>/{index,tree,abi}.json	Raw per-repo ingest output: file tree, parsed sources, ABI files
sources.json	The forks to index (generated from the fork waves)
examples/	Five worked examples (idea → components → repo layout), produced by the real pipeline
indexer/	ingest.py, build_index.py, validate.py, refresh_sources.py, compose.py (idea → plan → fetch), finalize.py

Use

sqlite3 index.sqlite "select slug,path,name from components where components match 'paymaster' limit 10"
pip install -r requirements.txt
BL_INDEX=. python3 indexer/compose.py plan "gasless NFT membership with a paymaster" --json plan.json
BL_INDEX=. python3 indexer/compose.py fetch plan.json out/

Reuse a fork (pinned install lines + licence note):

jq '.repos[] | select(.slug=="openzeppelin-contracts") | .reuse' catalog.json
jq -r '.categories["smart-contract-libraries"]' taxonomy/reuse.json

Raw files: https://raw.githubusercontent.com/Blockchains/blockchainlab-index/main/catalog.json.

Fully automated composition: blockchainlab-compose (CLI + compose.yml Action) turns an idea into a new Blockchains repo: capabilities → components from this index → pragma/licence checks → generated glue, tests, deploy script, CI → forge test → repo → CI result. Composed by it with no hand edits:

• forge-dao-governance-token
• forge-usd-priced-membership-nft

Composed with this index (CI green, deployed to Pages):

• forge-example-usd-savings-vault
• forge-example-gasless-membership

Licences

The index code is MIT. Indexed code keeps its own licence, recorded per repo and per file. compose.py will not copy source-available files (e.g. BUSL-1.1), and it flags GPL/LGPL so composed projects inherit the right terms.

Use as a building block

For AI agents and builders: read AGENTS.md (setup, commands, structure, rules), llms.txt (doc map) and the machine-readable blocks.json (schema). How all Blockchains blocks fit together: Build with Blocks · org catalogue: https://blockchains.github.io/blocks.json.

What it exports

Export	Type	Install / access
catalog.json	file	https://raw.githubusercontent.com/Blockchains/blockchainlab-index/main/catalog.json
components/<slug>.json	file	per-fork component list (path, kind, functions, events, SPDX, pragma, caps, raw URL)
index.sqlite	file	FTS5: select slug,path,name from components where components match 'paymaster'
indexer/compose.py	cli	BL_INDEX=. python3 indexer/compose.py plan "<idea>" --json plan.json && python3 indexer/compose.py fetch plan.json out/
taxonomy/capabilities.json	file	capability ids, synonyms, standards, match rules, licence policy

Minimal example (run on 2026-10-04 against the committed index)

git clone --depth 1 https://github.com/Blockchains/blockchainlab-index && cd blockchainlab-index
python3 -c "import sqlite3; print(sqlite3.connect('index.sqlite').execute(\"select slug,path,name from components where components match 'paymaster' limit 3\").fetchall())"
pip install -r requirements.txt
BL_INDEX=. python3 indexer/compose.py plan "gasless NFT membership with a paymaster" --json plan.json   # selected components + licence verdict

Inputs → outputs

• In: sources.json (file) forks to index (from fork-sync waves); idea (string) for compose.py plan
• Out: catalog (JSON) repo records incl. category, licence, commit, packages, install commands, reuse note; components (JSON); plan.json (JSON) capabilities → selected components + licence verdict

Composes with

• Blockchains/blockchainlab-compose: consumes catalog/components/taxonomy to generate projects
• Blockchains/fork-sync: keeps the indexed forks current; index runs after the sync
• Blockchains/awesome-blockchainlab: human-readable list of the same forks
• Blockchains/forge-example-gasless-membership: composed from this index
• Blockchains/forge-example-usd-savings-vault: composed from this index

Versioning & stability: beta. Rebuilt nightly (03:41 UTC). Record fields are additive; consumers should ignore unknown keys. Every component carries the fork commit it was indexed at, so pin that commit when copying code.