Operations Handbook

This section is the internal operating manual for Vela Labs. Use it when the team needs a precise answer, not a narrative answer.

The public docs explain how external developers integrate with VelaPay. This wiki explains how the team builds, verifies, deploys, and operates the system.

Source-of-Truth Hierarchy

When two artifacts disagree, use this order:

Rank	Source	Why
1	Running code and deployed state	The system either does this or it does not
2	vela-protocol IDL, program IDs, and deployment artifacts	Public protocol interface
3	vela-sdk exported types, builders, and event schemas	Compatibility adapter for all consumers
4	.planning/PROJECT.md, STATE.md, ROADMAP.md, REQUIREMENTS.md	Current intent, history, and requirement traceability
5	Internal wiki operations pages	Team process and runbooks
6	Public docs and repo READMEs	External explanation and onboarding
7	Root strategy docs 01 through 10	Historical product and market thesis

The only exception: when an ops runbook describes credential or deployment practice, follow the runbook unless live chain state proves it is stale.

What This Handbook Owns

Page	Use it for
Environment Registry	Program IDs, services, domains, secrets, and local paths
Release Management	Release order, gates, changelog discipline, and versioning
Repo Contracts	Which repo owns which interface, and which repos must change together
Verification Matrix	Commands to prove a rollout is integrated
Incident Response	Severity levels, first moves, rollback posture, and incident notes
Protocol Deployment Runbook	Devnet and mainnet protocol upgrade ceremony

Operating Principles

1. Protocol interfaces freeze before apps move. Do not update checkout, dashboard, webhook, or docs against a moving IDL.
2. The SDK is the compatibility adapter. If downstream repos need to know protocol details, prefer moving that detail into vela-sdk.
3. Mint is truth. Symbol is display. Token accounting and settlement always key off mint addresses, never token_symbol.
4. Program keypairs define addresses. Wallets define authority. Never confuse deployment identity with upgrade control.
5. Every release has proof. Build logs, test output, byte-hash checks, and smoke results matter more than confidence.
6. No silent fallback in money paths. Fallbacks are allowed only for explicit backwards compatibility and must be visible in docs/tests.
7. Private docs can be blunt. If a runbook contains an uncomfortable warning, keep it. The goal is operational clarity, not politeness.

Daily Use

Starting Work

1. Read Planning Status for current milestone state.
2. Read Repo Contracts to determine affected repos.
3. Check the target repo README for local commands.
4. If protocol interfaces are involved, start with vela-protocol and vela-sdk.

Before Deploying

1. Read Protocol Deployment Runbook.
2. Run the Verification Matrix gates.
3. Confirm the Environment Registry values.
4. Record any deviations in the release notes or incident log.

After Deploying

1. Verify deployed bytes and IDLs.
2. Verify event ingestion and webhook delivery.
3. Verify at least one user-facing flow.
4. Update public docs, READMEs, and this wiki if any contract changed.

Pages That Should Stay Boring

These pages are meant to be stable references. Do not turn them into status updates:

• environment registry
• repo contracts
• incident severity table
• deployment runbook
• verification matrix

Put temporary status in .planning/STATE.md, phase summaries, or release notes.