Release Management

This page defines how Vela Labs ships changes across the multi-repo workspace.

The main rule: release by dependency order, not by convenience.

Release Classes

Class	Examples	Required gates
Protocol interface release	Instruction args/accounts, account layout, events, program IDs	Protocol tests, SDK release gate, rollout verification, deployed byte/IDL verification
SDK-only release	New helper, CLI improvement, browser export	SDK release gate, package smoke test
Runtime app release	Dashboard, checkout, portal, admin, widget	App typecheck/build/tests, SDK pin verified
Docs/content release	Public docs, wiki, README	Site build, link checks where available
Emergency release	Pause, unpause, hotfix, event ingestion fix	Minimal failing test or reproduction, targeted fix, explicit post-check

Normal Protocol Release Order

1. vela-protocol
2. vela-sdk
3. vela-dashboard
4. vela-webhook
5. vela-checkout
6. vela-widget
7. vela-portal
8. vela-admin
9. vela-docs
10. vela-demo
11. internal-wiki

vela-web usually does not block protocol releases.

Commerce OS Release Order

Commerce changes that alter public types, event payloads, dashboard APIs, or hosted checkout deploy in this order:

1. Fresh/migrated D1 compatibility and backend consumer
2. @velapay/sdk and @velapay/webhook
3. Dashboard API and UI
4. Hosted checkout
5. Public docs
6. Internal wiki

Payment, refund, and protocol execution flags are independent. Start a rollout with execution disabled, complete read-only smoke checks, enable payments, verify one confirmed payment and reconciliation, then enable refunds. A failure disables the affected flag before Worker or D1 rollback.

The current accepted rollout is devnet-only. Follow vela-dashboard/docs/runbooks/v19-commerce-release-gates.md and record acceptance in vela-dashboard/docs/runbooks/v1.9-devnet-rollout-report.md.

Compatibility Pair

vela-protocol and vela-sdk are the mandatory compatibility pair.

If protocol IDL, accounts, or events change:

• SDK IDL must be updated
• SDK exported types must compile
• SDK event schemas must reflect public payloads
• downstream runtime repos must use the compatible SDK version or local path

Do not deploy protocol changes while the SDK still models the previous interface.

Pre-Release Checklist

Interface freeze

• [ ] Instruction accounts and args are final.
• [ ] Account layout is final.
• [ ] Event payloads are final.
• [ ] Program IDs are confirmed unchanged unless intentionally rotating.
• [ ] IDLs are regenerated or confirmed current.
• [ ] SDK IDL copies match protocol artifacts.

Consumer audit

• [ ] Search for affected fields across repos.
• [ ] Patch instruction builders.
• [ ] Patch deserializers.
• [ ] Patch event schemas and fixtures.
• [ ] Patch UI assumptions and token labels.
• [ ] Patch docs/examples.

Verification

• [ ] vela-protocol: bun run verify:rollout
• [ ] vela-protocol: bun run verify:deployed after deploy
• [ ] vela-sdk: bun run release:verify
• [ ] vela-dashboard: targeted worker/indexer tests
• [ ] vela-webhook: build and tests
• [ ] vela-checkout: typecheck
• [ ] vela-widget: typecheck
• [ ] docs/wiki builds if public explanation changed

Versioning Rules

SDK

Use semantic versioning:

Change	Version bump
Backwards-compatible helper or export	Patch
New optional protocol field support	Minor
Required instruction/account/event change	Minor before 1.0, major after 1.0
Runtime-breaking removal	Major after 1.0; avoid before 1.0 unless unavoidable

Pre-1.0 does not mean casual. Treat every published SDK release as externally consumed.

Protocol

Protocol has two kinds of versions:

• program identity: the Solana program address
• interface version: IDL/account/event shape

A program upgrade keeps the same identity but may still change the interface. Downstream releases care about the interface version, not only the address.

Release Notes Template

Use this format in internal notes or PR descriptions:

# Release: <name>

Date:
Operator:
Commit(s):

## Summary

## Protocol Impact

- Program IDs changed: yes/no
- IDL changed: yes/no
- Account layout changed: yes/no
- Event shape changed: yes/no
- Token semantics changed: yes/no

## Repos Updated

## Verification

## Deployment

## Rollback / Mitigation

## Follow-Up

Rollback Posture

Solana program upgrades are not like simple web rollbacks.

Surface	Rollback approach
Protocol program	Upgrade again to previous known-good artifact if authority allows
SDK	Publish fixed package or pin consumers back to previous version
Dashboard/webhook workers	Redeploy previous Worker build
Checkout/widget/portal/admin	Redeploy previous app build
Docs/wiki	Revert content and rebuild

For protocol, keep previous .so artifacts and IDLs for each deployed release. If a previous artifact is not available, rollback becomes reconstruction, not rollback.

Release Stop Conditions

Stop the release if any of these happen:

• program keypair address does not match manifest
• wallet is not the expected upgrade authority
• SDK IDL does not match protocol IDL
• verify:rollout fails
• on-chain byte hash does not match local artifact after deploy
• webhook schemas reject valid new events
• dashboard/worker rewrites token identity incorrectly
• any money path falls back silently
• a fake or unrelated signature can confirm a payment or refund
• browser input can change the configured Solana cluster
• concurrent refunds can reserve more than the paid balance
• an auditor mutation returns anything other than 403
• commerce outbox events cannot be replayed idempotently by event ID