vaas is a simplified implementation of the Interchain Security (ICS) protocol, derived from interchain-security. It provides core cross-chain validation functionality while removing complex features not needed for simpler deployments.
VAAS allows Cosmos blockchains to lease their proof-of-stake security to consumer chains. All active validators on the provider chain automatically validate all consumer chains - there is no opt-in/opt-out mechanism.
VAAS uses IBC v2 exclusively — no channel handshake, no port reservations.
The provider and consumer modules register on ibcRouterV2 under the
application IDs vaasprovider and vaasconsumer. After a consumer launches,
a relayer (the localnet and e2e suites use
ts-relayer) creates an
IBC v2 client on each chain pointing at the counterparty and registers the
path. The consumer's owner then declares those clients on each chain, and all
VSC packets flow over the declared client from the next epoch boundary.
Registering the v2 routes is necessary but nowhere near sufficient: a host chain
must also carry a set of wiring duties the modules cannot install themselves,
and most of them fail silently when omitted — one of them halts the provider
chain at the first consumer deletion. See
docs/embedding.md for the checklist.
app/provider/app.go demonstrates the full wiring;
app/consumer/app.go is a deliberately reduced reference
app, not a template.
| Feature | Description |
|---|---|
| Consumer Lifecycle | Full lifecycle management, including the PAUSED phase |
| Key Assignment | Validators can use different consensus keys per consumer chain |
| Infraction Parameters | Global slash/jail parameters for double-sign and downtime |
| VSC Packets | Validator set updates sent at epoch boundaries |
| Double Voting Evidence | Handle double voting evidence from consumers |
| Downtime Slashing | Falsifiable downtime evidence; slash held behind a challenge window |
| Light Client Misbehavior | Consumer client frozen and consumer paused; nobody punished; a governance resume waits out the fork's evidence |
| Consumer Metadata | Name, description, metadata for chain discovery |
| Feature | Reason |
|---|---|
| Partial Set Security (PSS) | All validators validate all consumers |
| Top N / Opt-In Chains | No validator selection per consumer |
| Power Shaping | No caps, allowlists, denylists, priority lists |
| ICS Consumer Reward Distribution | Replaced by a provider-side fee pool (see below) |
| Slash Packet Throttling | No rate-limiting across consumers |
| Per-Consumer Commission Rates | Validators use same commission as provider |
| IBC v1 Channel Support | IBC v2 only |
| Standalone-to-Consumer Changeover | Not currently supported (future work) |
Instead of ICS-style cross-chain reward distribution, each consumer prepays a
provider-side fee pool. Once per epoch the provider collects
fees_per_block * blocks_per_epoch from the pool and distributes it to the
bonded validators; a pool that cannot cover an epoch's fee flags the consumer
as in-debt and gates its user transactions. See
docs/consumer-fee-pool.md.
See docs/consumer-transition.md for the consequences and requirements of a future standalone-to-consumer transition.
make build # go build ./...
make test # unit tests (excludes e2e)
make lint # golangci-lint
# E2E (Docker-based, spins up provider + consumer + ts-relayer)
make docker-build-all
make test-e2e- Localnet setup — run a provider, a consumer, and
ts-relayerlocally - Embedding VAAS — the host-app wiring duties a chain integrating the modules must carry, and what breaks without each
- Security model — what a deployment trusts, what it punishes, and the residual assumptions
- Consumer launch runbook — end-to-end operator flow from registration to a funded, launched consumer
- Consumer lifecycle — phases, on-chain effects, operator/relayer responsibilities
- Consumer downtime — detection, verifiable evidence, optimistic slashing, challenges, and the PAUSED phase
- Consumer liveness — removal sweep, snapshot resync, and consumer safe mode
- Consumer refusal — refusal signal and threshold pause, punishment deferral behind removal votes, delayed equivocation punishment
- Consumer fee pool — funding, share accounting, withdrawal locks, and sweeping
- Consumer transition — future-work considerations for a standalone-to-consumer changeover
- Key assignment — per-consumer consensus keys and the assignment rules
- Equivocation and light-client evidence — submitting double-voting and misbehaviour evidence, and their consequences
- Validator obligations — the operational duties bonding on the provider imposes
- Parameters reference — every provider and consumer parameter: type, bound, default, where set
- Queries reference — every provider and consumer query, its CLI command, and what it returns
- Events reference — every event both modules emit, its attributes, and what is deliberately not an event
- Genesis / restart runbook — exporting and re-importing state, per-module round-trip guarantees, and the halt/upgrade flow
- End-to-end tests — the Docker e2e suites and how to run and extend them
- Contributor guide (AGENTS.md) — architecture, build/test commands, code layout
- Design rationale (DESIGN_RATIONALE.md) — why VAAS is shaped the way it is