VAAS (Validator-as-a-Service) is a simplified Interchain Security (ICS) implementation for Cosmos blockchains, derived from interchain-security. It lets a provider chain lease its proof-of-stake security to consumer chains via automatic validator synchronization. All active validators validate all consumers — no opt-in/opt-out.
VAAS runs on IBC v2 only (client-based, out-of-order). There is no IBC v1 channel handshake; the VAAS modules register on ibcRouterV2 under application IDs vaasprovider and vaasconsumer (see x/vaas/types/keys.go). Consumer launch relies on a relayer (ts-relayer in localnet and e2e) creating IBC v2 clients on both sides; the consumer's owner then declares them on each chain, and the provider serves the declared client from the next epoch boundary.
make build # go build ./...
make test # all unit tests (excludes e2e), 25m timeout
make lint # golangci-lint via devdeps/go.mod
make lint-fix # auto-fix lint issues
make mocks-gen # regenerate mocks from x/vaas/types/expected_keepers.go
make vulncheck # govulncheck
# Single test
go test ./x/vaas/provider/keeper -run TestConsumerClientId -v
# Protobuf (requires Docker)
make proto-gen # generate Go code from .proto files
make proto-format # clang-format
make proto-lint # buf lint
# Localnet (3 terminals, or use localnet-start for all-in-one)
make localnet-start # provider + consumer + ts-relayer (Docker)
make localnet-clean # stop all, clean data
# E2E (Docker-based)
make docker-build-all # build chain image (ts-relayer image is pulled)
make test-e2e # run e2e suiteDev tool dependencies are isolated in devdeps/go.mod and invoked via go run -modfile devdeps/go.mod.
The core protocol lives in x/vaas/ with two symmetric modules:
x/vaas/provider/— runs on the provider chain. Manages consumer lifecycle, generates VSC (Validator Set Change) packets at epoch boundaries, handles key assignment, processes double-voting evidence.x/vaas/consumer/— runs on consumer chains. Receives VSC packets, maintains VAAS validator set, reports evidence back to provider.x/vaas/types/— shared types, errors, constants, andexpected_keepers.go(interfaces for external dependencies like staking/slashing).
Each module has: keeper/ (business logic + state), types/ (data structures + params), client/cli/ (CLI commands), module.go, and ibc_module.go (IBC v2 callbacks implementing api.IBCModule from ibc-go/v10/modules/core/api).
Two helper modules replace the standard Cosmos modules on the provider app so the staking module does not push its own validator-set updates to CometBFT -- the VAAS provider module computes and returns the provider validator set itself, in EndBlock:
x/vaas/no_valupdates_staking/— staking without EndBlock valset exportsx/vaas/no_valupdates_genutil/— genutil without gentx-based valset init
The consumer app wires neither: it runs no real staking module and uses stock genutil with the ConsumerKeeper standing in as a no-op staking keeper, so a consumer's validator set is driven entirely by incoming VSC packets.
app/provider/— full Cosmos SDK app for the provider chainapp/consumer/— full Cosmos SDK app for consumer chainsapp/cmd/— binary entry points (providerandconsumerdaemons)
Built with make build-apps into build/.
- Once a consumer reaches
LAUNCHED, a relayer creates an IBC v2 client on each chain pointing at the other (with counterparties registered). The consumer's owner then declares them:MsgUpdateConsumer'sclient_idbinds the provider side,MsgSetProviderClientpins the consumer side. Neither chain creates or infers a client itself. - Once per epoch (
blocks_per_epoch, default 600) the provider queues a VSC packet per launched consumer and, in the same window, collects each consumer's epoch fee (fees_per_block * blocks_per_epoch) from its fee pool and distributes it to the bonded validators. - Provider sends each queued VSC packet over the declared IBC v2 client. Packets are out-of-order; the consumer deduplicates via
HighestValsetUpdateID. A packet carries a diff by default, or an absolute snapshot (is_snapshot) when the consumer has fallen behind on acks, and every packet also carries the consumer's current in-debt flag. - Consumer's
OnRecvPacketcallsApplyVaasValidatorChanges()and the new set is flushed to CometBFT on the nextEndBlock. - Evidence flows back to the provider two ways. Downtime evidence travels consumer -> provider as IBC
EvidencePacketDatapackets, which the provider prices into a slash held behind a challenge window (a successfulMsgChallengeConsumerDowntimecancels it and moves the consumer toPAUSED). Double-voting / light-client evidence is submitted as ordinary provider transactions (MsgSubmitConsumerDoubleVoting/MsgSubmitConsumerMisbehaviour). Global infraction parameters determine slash/jail; a verified double-vote jails at once but slashes and tombstones only afterequivocation_execution_delay, and both that and matured downtime slashes wait out a removal vote for the consumer that is in its voting period (see docs/consumer-refusal.md).
REGISTERED -> INITIALIZED -> LAUNCHED -> STOPPED -> DELETED, plus a PAUSED
branch off LAUNCHED (entered by a successful downtime challenge or by the
bonded power refusing the consumer reaching refusal_pause_threshold;
governance resumes it to LAUNCHED or removes it to STOPPED).
Managed on the provider via MsgCreateConsumer, MsgUpdateConsumer,
MsgRemoveConsumer, MsgChallengeConsumerDowntime, MsgSetConsumerRefusal,
and MsgResumeConsumer;
the per-consumer fee pool via MsgFundConsumerFeePool,
MsgWithdrawConsumerFeePool, MsgSweepConsumerFeePool, and
MsgSetConsumerFeesPerBlock.
Uses cosmossdk.io/collections for type-safe key-value storage. Each keeper defines a Schema with indexed maps. Key assignment state maps validator addresses to per-consumer consensus keys (ValidatorConsumerPubKey, ValidatorByConsumerAddr).
Under proto/vaas/: v1/ (shared wire types like ValidatorSetChangePacketData), provider/v1/, consumer/v1/. Generated Go code goes to corresponding types/ packages.
- Unit tests: alongside source in
*_test.go. Usetestutil/keeper/unit_test_helpers.gofor in-memory keeper setup withMockedKeepers(gomock). - Mock generation:
make mocks-genfromx/vaas/types/expected_keepers.go->testutil/keeper/mocks.go - E2E tests:
tests/e2e/— Docker-based, spins up real provider/consumer chains plus theghcr.io/allinbits/ibc-v2-ts-relayercontainer; see tests/e2e/e2e_tsrelayer_test.go.
Import groups (enforced by gci in .golangci.yml):
- Standard library
- Third-party
github.com/cometbft/cometbftgithub.com/cosmos/*,cosmossdk.io/*,github.com/cosmos/cosmos-sdkgithub.com/allinbits/vaas(this module)
Generated files (*.pb.go, *.pb.gw.go) are excluded from linting; test files and the e2e and app modules are linted.