release-conventions

name	release-conventions
description	Naming conventions for tags, releases, and SPKGs in the substreams-svm 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-svm"}

Release & Packaging Conventions

Naming conventions and release workflow for the Pinax substreams-svm monorepo.

URL Pattern

https://github.com/pinax-network/substreams-svm/releases/download/<tag>/<spkg-filename>

Examples:

• https://github.com/pinax-network/substreams-svm/releases/download/svm-dex-v0.3.1/clickhouse-svm-dex-v0.3.1.spkg
• https://github.com/pinax-network/substreams-svm/releases/download/svm-balances-v0.2.0/clickhouse-svm-balances-v0.2.0.spkg

Tag Format

svm-<type>-v<version>

Examples: svm-dex-v0.3.1, svm-balances-v0.2.0, svm-transfers-v0.1.0

Release Name

svm-<type> v<version>

Examples: svm-dex v0.3.1, svm-balances v0.2.0

SPKG Naming

Each crate may produce up to 3 SPKGs. All share the same version number.

Type	Pattern	Example
Base DB module	svm-<type>-v<version>.spkg	svm-dex-v0.3.1.spkg
ClickHouse sink	clickhouse-svm-<type>-v<version>.spkg	clickhouse-svm-dex-v0.3.1.spkg
PostgreSQL sink	postgres-svm-<type>-v<version>.spkg	postgres-svm-dex-v0.3.1.spkg

Key: Engine prefix comes first (clickhouse- / postgres-), then svm-<type>.

substreams.yaml Package Names

Type	Pattern	Example
Base DB module	svm_<type>	svm_dex
ClickHouse sink	svm_<type>_clickhouse	svm_dex_clickhouse
PostgreSQL sink	svm_<type>_postgres	svm_dex_postgres

SPKG Distribution

SPKGs must be placed in two locations:

1. ./spkg/ folder in the repo (so downstream modules can import them)
2. GitHub release assets (for external consumers / k8s templates)

Release Workflow

1. Bump version in all relevant substreams.yaml files (base, clickhouse, postgres)
2. Update import paths in clickhouse/postgres substreams.yaml to reference the new base spkg version
3. Build: cargo build --target wasm32-unknown-unknown --release -p <crate>
4. Pack each module: substreams pack in the base, clickhouse, and postgres directories
5. Copy SPKGs to ./spkg/ (with correct naming) and remove old versions
6. Commit version bumps + spkg files
7. Tag: git tag -a svm-<type>-v<version> -m "svm-<type> v<version>"
8. Push commit and tag
9. 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

The SVM repo uses a flat structure with db-svm-* prefixed directories for sink layers:

db-svm-<type>/                    # Base DB module
├── substreams.yaml
├── src/lib.rs
├── Cargo.toml
db-svm-<type>-clickhouse/         # ClickHouse sink
├── substreams.yaml
├── schema.*.sql                     # Split schema files
├── Makefile
db-svm-<type>-postgres/           # PostgreSQL sink
├── substreams.yaml
├── schema.sql

Individual DEX Module SPKGs

Individual DEX modules (e.g., raydium-amm-v4, pumpfun, jupiter-v6) are also published as SPKGs and referenced by the aggregate db-svm-dex module via imports:

raydium-amm-v4-v0.2.0.spkg
pumpfun-bonding-curve-v0.2.2.spkg
jupiter-v6-v0.2.0.spkg