| name | release-conventions |
| description | Naming conventions for tags, releases, and SPKGs in the substreams-evm monorepo. Use when creating releases, tagging versions, or publishing packages. |
| license | Apache-2.0 |
| compatibility | {"platforms":["claude-code","cursor","vscode","windsurf"]} |
| metadata | {"version":"1.0.0","author":"Pinax Network","documentation":"https://github.com/pinax-network/substreams-evm"} |
Release & Packaging Conventions
Naming conventions and release workflow for Pinax substreams-* monorepos.
URL Pattern
https://github.com/pinax-network/substreams-<chain>/releases/download/<chain>-<type>-v<version>/<chain>-clickhouse-<type>-v<version>.spkg
Examples:
https://github.com/pinax-network/substreams-evm/releases/download/evm-contracts-v0.4.0/evm-clickhouse-contracts-v0.4.0.spkghttps://github.com/pinax-network/substreams-evm/releases/download/evm-balances-v0.3.3/evm-clickhouse-balances-v0.3.3.spkghttps://github.com/pinax-network/substreams-svm/releases/download/svm-dex-v0.2.5/svm-clickhouse-dex-v0.2.5.spkg
Tag Format
<chain>-<type>-v<version>
Examples: evm-contracts-v0.4.0, evm-dex-v0.4.0, svm-dex-v0.2.5
Release Name
<chain>-<type> v<version>
Examples: evm-contracts v0.4.0, evm-dex v0.4.0
SPKG Naming
Each crate produces up to 3 SPKGs. All share the same version number.
| Type | Pattern | Example |
|---|
| Base DB module | <chain>-<type>-v<version>.spkg | evm-contracts-v0.4.0.spkg |
| ClickHouse sink | <chain>-clickhouse-<type>-v<version>.spkg | evm-clickhouse-contracts-v0.4.0.spkg |
| PostgreSQL sink | <chain>-postgres-<type>-v<version>.spkg | evm-postgres-contracts-v0.4.0.spkg |
Key: Chain prefix comes first, then engine (clickhouse / postgres), then type.
substreams.yaml Package Names
| Type | Pattern | Example |
|---|
| Base DB module | <chain>_<type> | evm_contracts |
| ClickHouse sink | <chain>_clickhouse_<type> | evm_clickhouse_contracts |
| PostgreSQL sink | <chain>_postgres_<type> | evm_postgres_contracts |
SPKG Distribution
SPKGs must be placed in two locations:
./spkg/ folder in the repo (so downstream modules can import them)- GitHub release assets (for external consumers / k8s templates)
Release Workflow
- Bump version in all relevant
substreams.yaml files (base, clickhouse, postgres)
- Update import paths in clickhouse/postgres
substreams.yaml to reference the new base spkg version
- Build:
cargo build --target wasm32-unknown-unknown --release -p <crate>
- Pack each module:
substreams pack in the base, clickhouse, and postgres directories
- Copy SPKGs to
./spkg/ (with correct naming) and remove old versions
- Commit version bumps + spkg files
- Tag:
git tag -a <chain>-<type>-v<version> -m "<chain>-<type> v<version>"
- Push commit and tag
- Create GitHub release with the tag, attach all 3 SPKGs as assets
Version Alignment
All 3 SPKGs for a given crate (base, clickhouse, postgres) must share the same version.
Directory Structure
evm-<type>/ # DB module (contains everything)
├── substreams.yaml # Base DB module
├── src/lib.rs
├── Cargo.toml
├── clickhouse/
│ ├── substreams.yaml # ClickHouse sink (imports base spkg)
│ ├── schema.sql
│ └── Makefile
└── postgres/
├── substreams.yaml # PostgreSQL sink (imports base spkg)
├── schema.sql
└── Makefile
