Skip to content

Commit c5289e1

Browse files
giunatalegiunatale
authored
chore: refresh docs (#42)
* refresh docs * revise to document consumer transition * address f/b
1 parent 0df4c58 commit c5289e1

7 files changed

Lines changed: 512 additions & 117 deletions

File tree

‎AGENTS.md‎

Lines changed: 10 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -4,7 +4,7 @@
44

55
VAAS (Validator-as-a-Service) is a simplified Interchain Security (ICS) implementation for Cosmos blockchains, derived from [interchain-security](https://github.com/cosmos/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.
66

7-
Supports both IBC v1 (channel-based, ordered) and IBC v2 (client-based, out-of-order). IBC v2 uses application IDs `vaas/provider` and `vaas/consumer` instead of port IDs.
7+
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](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 provider then discovers its consumer client at the next epoch boundary.
88

99
## Build & Test Commands
1010

@@ -25,11 +25,11 @@ make proto-format # clang-format
2525
make proto-lint # buf lint
2626

2727
# Localnet (3 terminals, or use localnet-start for all-in-one)
28-
make localnet-start # provider + consumer + Hermes relayer
28+
make localnet-start # provider + consumer + ts-relayer (Docker)
2929
make localnet-clean # stop all, clean data
3030

3131
# E2E (Docker-based)
32-
make docker-build-all # build chain + Hermes images
32+
make docker-build-all # build chain image (ts-relayer image is pulled)
3333
make test-e2e # run e2e suite
3434
```
3535

@@ -45,7 +45,7 @@ The core protocol lives in `x/vaas/` with two symmetric modules:
4545
- **`x/vaas/consumer/`** — runs on consumer chains. Receives VSC packets, maintains cross-chain validator set, reports evidence back to provider.
4646
- **`x/vaas/types/`** — shared types, errors, constants, and `expected_keepers.go` (interfaces for external dependencies like staking/slashing).
4747

48-
Each module has: `keeper/` (business logic + state), `types/` (data structures + params), `client/cli/` (CLI commands), `module.go`, `ibc_module.go` (v1 callbacks), `ibc_module_v2.go` (v2 callbacks).
48+
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`).
4949

5050
Two helper modules replace standard Cosmos modules to prevent automatic validator set updates on consumer chains:
5151

@@ -62,10 +62,11 @@ Built with `make build-apps` into `build/`.
6262

6363
### Key Data Flow
6464

65-
1. Provider detects staking changes → queues VSC packets (every `blocks_per_epoch` blocks, default 600)
66-
2. VSC packets sent via IBC to all registered consumers
67-
3. Consumer receives packet → calls `ApplyCCValidatorChanges()` to update its validator set
68-
4. Double-voting evidence flows consumer → provider, where per-consumer infraction parameters determine slash/jail
65+
1. Once a consumer reaches `LAUNCHED`, a relayer creates an IBC v2 client on the provider pointing to the consumer (and the counterparty on the other side). The provider discovers this client at the next epoch boundary (`discoverActiveConsumerClient`), it never creates the client itself.
66+
2. Provider computes validator set changes once per epoch (`blocks_per_epoch`, default 600) and queues a VSC packet per launched consumer.
67+
3. Provider sends each queued VSC packet over the discovered IBC v2 client. Packets are out-of-order; the consumer deduplicates via `HighestValsetUpdateID`.
68+
4. Consumer's `OnRecvPacket` calls `ApplyCCValidatorChanges()` and the new set is flushed to CometBFT on the next `EndBlock`.
69+
5. Double-voting / light-client evidence flows consumer → provider via `MsgSubmitConsumerDoubleVoting` / `MsgSubmitConsumerMisbehaviour`; per-consumer infraction parameters determine slash/jail.
6970

7071
### Consumer Lifecycle
7172

@@ -85,7 +86,7 @@ Under `proto/vaas/`: `v1/` (shared wire types like `ValidatorSetChangePacketData
8586

8687
- **Unit tests**: alongside source in `*_test.go`. Use `testutil/keeper/unit_test_helpers.go` for in-memory keeper setup with `MockedKeepers` (gomock).
8788
- **Mock generation**: `make mocks-gen` from `x/vaas/types/expected_keepers.go` → `testutil/keeper/mocks.go`
88-
- **E2E tests**: `tests/e2e/` — Docker-based, spins up real chains with Hermes relayer.
89+
- **E2E tests**: `tests/e2e/` — Docker-based, spins up real provider/consumer chains plus the `ghcr.io/allinbits/ibc-v2-ts-relayer` container; see [tests/e2e/e2e_tsrelayer_test.go](tests/e2e/e2e_tsrelayer_test.go).
8990

9091
## Lint / Import Ordering
9192

‎DESIGN_RATIONALE.md‎

Lines changed: 134 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,134 @@
1+
# VAAS Design Rationale
2+
3+
> This document supersedes [`PLAN.old.md`](PLAN.old.md), the original rewrite
4+
> plan drafted before the port from `interchain-security`. `PLAN.old.md` is
5+
> kept for historical reference only; the present document is the
6+
> authoritative statement of why VAAS is shaped the way it is.
7+
8+
This is a forward-facing reference for contributors. For the per-feature
9+
historical diff against the `interchain-security` codebase VAAS was ported
10+
from, see [`REWRITE_SUMMARY.md`](REWRITE_SUMMARY.md); for protocol-level
11+
mechanics, see [`docs/consumer-lifecycle.md`](docs/consumer-lifecycle.md) and
12+
[`AGENTS.md`](AGENTS.md).
13+
14+
VAAS is a **simplified** Interchain Security: a Cosmos provider chain lends
15+
its full validator set to one or more consumer chains, automatically, with no
16+
opt-in/out and no power shaping. The simplification is the product, not a
17+
work-in-progress.
18+
19+
---
20+
21+
## Guiding Principles
22+
23+
1. **All validators validate everything.** There is no per-consumer
24+
selection. The active provider set, capped at
25+
`MaxProviderConsensusValidators`, is the consumer set.
26+
2. **No cross-chain economics inside the protocol.** No reward distribution,
27+
no per-consumer commission rates, no slash throttling, no slash meters.
28+
Consumers stand up their own fee/reward models; the protocol carries only
29+
validator-set state and security signals.
30+
3. **IBC v2 only.** No channel handshake, no ordered channels, no port
31+
reservations. VAAS modules register on `ibcRouterV2` under the application
32+
IDs `vaasprovider` and `vaasconsumer`; consumer launch relies on a relayer
33+
creating the IBC v2 clients and the provider discovering its consumer
34+
client at the next epoch boundary.
35+
4. **Forward-only consumer lifecycle.** `REGISTERED → INITIALIZED → LAUNCHED
36+
→ STOPPED → DELETED`, with a single rollback path (failed launch → back to
37+
`REGISTERED`). Standalone-to-consumer changeover is not currently
38+
supported; see [`docs/consumer-transition.md`](docs/consumer-transition.md)
39+
for the future-work considerations.
40+
5. **Provider authority for control-plane messages.** `OnSendPacket` requires
41+
the keeper's authority as signer; consumers never send packets back
42+
(`OnRecvPacket` on the provider is a failure path; `OnSendPacket` on the
43+
consumer is rejected). Misbehaviour reports travel as ordinary provider
44+
transactions, not IBC packets.
45+
46+
---
47+
48+
## Why the Simplifications
49+
50+
### Removed: Partial Set Security (PSS), Top N, Opt-in, Power Shaping
51+
52+
The `interchain-security` codebase supports renting *subsets* of the
53+
validator set per consumer with caps, allowlists, denylists, priority lists,
54+
and inactive-validator participation (ADR-017). VAAS targets deployments
55+
where the provider guarantees its entire active set to every consumer.
56+
Removing PSS deletes a large surface area: per-validator opt-in state,
57+
per-consumer power-shaping parameters, "has-to-validate" queries, and the
58+
messages that maintain them (`MsgOptIn`, `MsgOptOut`,
59+
`MsgSetConsumerCommissionRate`).
60+
61+
The trade-off is rigidity: a consumer cannot pick a smaller validator set.
62+
That is intentional. Smaller sets do not inherit the BFT assumption of the
63+
full set, there is no assumption that can be made about smaller sets, no
64+
security guarantee. The simplification also drastically reduces the
65+
complexity of the system.
66+
67+
### Removed: Slash Packet Throttling, Slash Meters, Slash Retry
68+
69+
ICS throttles slash packets to bound the impact of a misbehaving or
70+
adversarial consumer on the provider's validator set. VAAS removes the
71+
throttle, the meter, and the retry queue. Consumer-initiated slashing for
72+
downtime is *not currently performed by the provider*; equivocation evidence
73+
(double-sign, light-client) is submitted as a provider transaction
74+
(`MsgSubmitConsumerDoubleVoting`, `MsgSubmitConsumerMisbehaviour`) and
75+
slashed using per-consumer infraction parameters. Downtime slashing via slash
76+
packets is an open design question (see open issues / PRs).
77+
78+
### Removed: Consumer Reward Distribution
79+
80+
ICS pipes a fraction of consumer fees back to the provider as validator
81+
rewards. VAAS leaves the consumer fee model entirely to the consumer chain.
82+
This eliminates a category of cross-chain accounting and the related
83+
provider-side state (reward denom registration, fee pool addressing, etc.).
84+
85+
### Kept: Per-Consumer Infraction Parameters
86+
87+
Each consumer carries its own `infraction_parameters` (double-sign and
88+
downtime slash fractions, jail durations, tombstone flag). This is the one
89+
place per-consumer customisation survives — the protocol cannot decide
90+
slash severity centrally because consumers vary in security profile.
91+
92+
### Kept: Key Assignment
93+
94+
Validators may assign per-consumer consensus keys via
95+
`MsgAssignConsumerKey`. Keys are ed25519 only and prune on unbonding, with
96+
checks that prevent key reuse across consumers.
97+
98+
---
99+
100+
## Active Work and Open Questions
101+
102+
Live work is tracked in GitHub issues and pull requests, not in this file —
103+
this list points to the rough areas, not the specific tickets.
104+
105+
- **Genesis import/export**. Several entry points in the provider and
106+
consumer modules still need correct round-trip support. The provider
107+
`InitGenesis` path uses the chain-ID field as the consumer-id key, which
108+
needs cleaning up.
109+
- **Per-consumer infraction parameters at runtime**. The parameters are
110+
stored per consumer but the equivocation handling path needs to consume
111+
them consistently.
112+
- **Provider-side downtime slashing.** Whether (and how) consumers should be
113+
able to request downtime slashing on the provider is an open design
114+
question; a draft PR proposes a slash-packet-based path.
115+
- **Timeout policy.** A VSC packet timeout currently has heavy consequences
116+
(consumer removal); whether this is the right default is open.
117+
- **Standalone-to-consumer transition.** The `PreVAAS` / `PrevStandaloneChain`
118+
collections and the `standaloneStakingKeeper` plumbing in the consumer
119+
module are dead today but preserved deliberately as a reference for a
120+
future transition implementation; see
121+
[`docs/consumer-transition.md`](docs/consumer-transition.md).
122+
123+
## Explicit Non-Goals
124+
125+
The following are intentionally **not** part of VAAS and should not be added
126+
back without a strong, documented reason:
127+
128+
- Partial Set Security (Top N, opt-in/out, allow/deny lists)
129+
- Per-consumer power shaping (caps, priority lists)
130+
- Slash packet throttling / slash meters
131+
- Cross-chain reward distribution
132+
- Per-consumer commission rates
133+
- IBC v1 channel routing for VAAS messages
134+
- Inactive provider validators participating in consumer security (ADR-017)

PLAN.md renamed to PLAN.old.md

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,12 @@
11
# VAAS Rewrite Plan
22

3+
> **Historical document.** This was the original plan drafted *before* the
4+
> port of `interchain-security` into VAAS, when the new module was still
5+
> being scoped. Paths, function names, and tooling assumptions reflect that
6+
> moment and are no longer accurate. It is kept verbatim for archival
7+
> reference. For the current authoritative statement of why VAAS is shaped
8+
> the way it is, see [`DESIGN_RATIONALE.md`](DESIGN_RATIONALE.md).
9+
310
Rewrite `x/vaas/provider` and `x/vaas/consumer` in a new `vaas` folder as a **new Go module** with package path `github.com/allinbits/vaas`.
411

512
---

‎README.md‎

Lines changed: 25 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -6,12 +6,20 @@
66

77
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.
88

9-
## Features
9+
## IBC v2 only
1010

11-
## IBC v2 support
11+
VAAS uses IBC v2 exclusively — no channel handshake, no port reservations.
12+
The provider and consumer modules register on `ibcRouterV2` under the
13+
application IDs `vaasprovider` and `vaasconsumer`. After a consumer launches,
14+
a relayer (the localnet and e2e suites use
15+
[`ts-relayer`](https://github.com/allinbits/ibc-v2-ts-relayer)) creates an
16+
IBC v2 client on each chain pointing at the counterparty and registers the
17+
path. The provider then discovers its consumer client at the next epoch
18+
boundary; all VSC packets flow over that client. Wiring VAAS into a host app
19+
just means adding the v2 routes — see [`app/provider/app.go`](app/provider/app.go)
20+
and [`app/consumer/app.go`](app/consumer/app.go) for reference.
1221

13-
The VAAS implementation supports IBC v2 only.
14-
IBC v2 is easily wireable by adding the IBC router v2 in a ibc-go >= 10.x.y compatible chain.
22+
## Features
1523

1624
### Kept from ICS
1725

@@ -37,7 +45,10 @@ IBC v2 is easily wireable by adding the IBC router v2 in a ibc-go >= 10.x.y comp
3745
| Slash Packet Throttling | Simplified slash handling |
3846
| Per-Consumer Commission Rates | Validators use same commission as provider |
3947
| IBC v1 Channel Support | IBC v2 only |
40-
| Standalone-to-Consumer Changeover | Only new chains as consumers |
48+
| Standalone-to-Consumer Changeover | Not currently supported (future work) |
49+
50+
See [docs/consumer-transition.md](docs/consumer-transition.md) for the
51+
consequences and requirements of a future standalone-to-consumer transition.
4152

4253
## Build & Test
4354

@@ -51,6 +62,15 @@ make docker-build-all
5162
make test-e2e
5263
```
5364

65+
## Documentation
66+
67+
- [Localnet setup](app/README.md) — run a provider, a consumer, and `ts-relayer` locally
68+
- [Consumer lifecycle](docs/consumer-lifecycle.md) — phases, on-chain effects, operator/relayer responsibilities
69+
- [Contributor guide (AGENTS.md)](AGENTS.md) — architecture, build/test commands, code layout
70+
- [Design rationale (DESIGN_RATIONALE.md)](DESIGN_RATIONALE.md) — why VAAS is shaped the way it is
71+
- [Diff vs the ICS codebase VAAS ported from (REWRITE_SUMMARY.md)](REWRITE_SUMMARY.md) — what was removed/kept in the port
72+
- [PLAN.old.md](PLAN.old.md) — the original pre-port rewrite plan, kept for archival reference
73+
5474
## Learn More
5575

5676
- [ICS Documentation](https://cosmos.github.io/interchain-security/)

0 commit comments

Comments
 (0)