feat: IBC v2 support by clockworkgr · Pull Request #18 · allinbits/vaas

clockworkgr · 2026-02-05T10:02:23Z

Closes #6

This PR reworks VaaS from IBC v1 (channel-based, ordered) to IBC v2 (client-based, out-of-order).

Key changes

Routing: channel-based → application-ID-based

Replaced port IDs (provider/consumer) with app IDs (vaasprovider/vaasconsumer) registered on the IBC v2 router
Packet routing now uses SendPacket(clientId) directly — no channels or connections

State tracking: channel ID → client ID

Consumer chains are now identified by IBC client ID instead of channel ID
provider_channel_id removed from consumer genesis; channel_id removed from provider ConsumerState
Provider uses discoverActiveConsumerClient() to auto-select the best client being actively updated by a relayer

Packet delivery: ordered → out-of-order with dedup

Consumer tracks HighestValsetUpdateID and silently skips stale VSC packets
No explicit sequence number needed

Removed IBC v1 concepts

Channel handshake callbacks (OnChanOpenInit/Try/Ack/Confirm)
HandshakeMetadata wire type
template_client param (replaced by ConsumerInitializationParameters)
connection_id from consumer genesis, provider genesis, and ConsumerInitializationParameters
ChannelKeeper, ConnectionKeeper, IBCCoreKeeper dependencies
Hermes relayer and its config/scripts/Dockerfile

Relayer: Hermes → ibc-v2-ts-relayer

E2E tests now use ghcr.io/allinbits/ibc-v2-ts-relayer for IBC v2 path creation and packet relaying

Proto field renumbering

All message fields are linearly increasing (no gaps). Removed fields caused renumbering in:

Params (provider), ConsumerState (provider genesis), GenesisState (consumer genesis)
ConsumerGenesisState, ProviderInfo, ChainInfo, ConsumerInitializationParameters

Assumptions

Only IBC v2 genesis supported (no v1 backward-compatible genesis)
Out-of-order VSC delivery is acceptable; consumer applies latest valset_update_id
template_client deprecated in favour of ConsumerInitializationParameters (different client types expected)
Provider stops and removes consumer on VSC timeouts (as per original design)
Consumer registration has been modified to work with IBC v2

- Update ibc-go to v10.5.0 with IBC v2 (Eureka) support - Add IBC v2 application identifiers (ProviderAppID, ConsumerAppID) - Add IBCPacketHandler interface for v2 client-based routing - Mark channel/connection keeper interfaces as deprecated - Remove HandshakeMetadata from wire protocol - Update IBC module handshake to use version string directly - Document client-based key mappings in provider types

Provider module: - Mark channelKeeper and connectionKeeper as deprecated - Add IBC v2 migration notes to OnAcknowledgementPacket and OnTimeoutPacket Consumer module: - Add HighestValsetUpdateID storage for out-of-order packet handling - Update OnRecvVSCPacket to skip stale packets (IBC v2 compatibility) - Mark channelKeeper, connectionKeeper, and ibcCoreKeeper as deprecated - Add key prefix for HighestValsetUpdateIDKey

- Mark template_client as deprecated (per-consumer config recommended) - Add IBC v2 note to connection_id field - Regenerate proto files

Add deprecation comments to channel handshake callbacks in both provider and consumer IBC modules, marking them as IBC v1 patterns that will be replaced by client-based routing in IBC v2 (Eureka). Changes: - Provider ibc_module.go: deprecate channel callbacks (OnChanOpen*, OnChanClose*) - Consumer ibc_module.go: deprecate channel callbacks and validation - Consumer genesis.proto: deprecate provider_channel_id and connection_id - Consumer genesis.go: add IBC v2 migration notes

Add IBC v2 migration documentation to registration flow and genesis handling: - consumer_lifecycle.go: document RegisterCounterparty as launch trigger - genesis.go: add notes about client-based vs channel-based routing - genesis.proto: deprecate channel_id in ConsumerState - tx.proto: add IBC v2 note to MsgCreateConsumer

Regenerate test mocks to include the new IBCPacketHandler interface added for IBC v2 packet sending. This interface provides a clean abstraction for packet sending that can be used with both v1 and v2.

Add IBC v2 (Eureka) packet sending support alongside existing v1 channel-based routing for backward compatibility during migration. Changes: - Add SendIBCPacketV2 function for client-based routing in utils.go - Add ibcPacketHandler field and SetIBCPacketHandler method to provider keeper - Add SendVSCPacketsToChainV2 for v2 packet sending - Update SendVSCPackets to try v2 routing when no channel exists - Update field count validation to 16 (with optional ibcPacketHandler) The provider now supports dual-mode operation: 1. Channel-based (v1): Used when consumer has an established channel 2. Client-based (v2): Used when consumer has a client but no channel

Add IBC v2 callback handlers for processing acknowledgements and timeouts using client-based routing instead of channel-based routing. New handlers: - OnAcknowledgementPacketV2: handles acks using client ID lookup - OnTimeoutPacketV2: handles timeouts using client ID lookup These handlers use GetClientIdToConsumerId for reverse lookup from client ID to consumer ID, enabling proper consumer identification in the IBC v2 routing model.

Add IBC v2 client-based packet reception handler for the consumer module. Changes: - Add OnRecvVSCPacketV2 for client-based VSC packet handling - Add ErrInvalidProviderClient error for v2 client validation - Provider identification via client ID instead of channel ID - Maintains out-of-order packet handling from v1 The consumer now supports dual-mode packet reception: 1. Channel-based (v1): OnRecvVSCPacket with channel validation 2. Client-based (v2): OnRecvVSCPacketV2 with client validation

Implement IBCModuleV2 for both provider and consumer that handles IBC v2 (Eureka) client-based routing: Provider (ibc_module_v2.go): - OnSendPacket: validates payload and logs VSC packet sending - OnRecvPacket: rejects packets (provider only sends, doesn't receive) - OnTimeoutPacket: triggers consumer removal via OnTimeoutPacketV2 - OnAcknowledgementPacket: handles acks via OnAcknowledgementPacketV2 Consumer (ibc_module_v2.go): - OnSendPacket: rejects (consumer doesn't send packets in VAAS) - OnRecvPacket: processes VSC packets via OnRecvVSCPacketV2 - OnTimeoutPacket/OnAcknowledgementPacket: logs unexpected calls These modules can be registered with IBC v2's router using application identifiers (vaas/provider, vaas/consumer) instead of port/channel pairs.

Add comprehensive tests for IBC v2 (Eureka) functionality: Consumer tests (relay_test.go): - TestOnRecvVSCPacketV2: Tests client-based packet reception and provider client establishment - TestOnRecvVSCPacketV2OutOfOrder: Tests out-of-order packet handling where older packets are acknowledged but ignored Provider tests (relay_test.go - new file): - TestOnAcknowledgementPacketV2: Tests error ack handling triggers consumer removal - TestOnTimeoutPacketV2: Tests timeout triggers consumer removal - TestClientIdToConsumerIdMapping: Tests bidirectional mapping These tests verify the IBC v2 client-based routing behavior and out-of-order packet handling for VSC packets.

Add compile-time checks to ensure IBCModuleV2 types implement the api.IBCModule interface from ibc-go v10: - Provider IBCModuleV2 verified against api.IBCModule - Consumer IBCModuleV2 verified against api.IBCModule This ensures the v2 modules are correctly implemented and will fail at compile time if the interface changes.

Add test for the HighestValsetUpdateID getter/setter which is used in IBC v2 to track the highest processed valset update ID for out-of-order packet handling.

Add tests for the provider's IBC v2 packet sending functionality: - TestSendVSCPacketsToChainV2NoHandler: Verifies graceful handling when no IBC packet handler is configured (packets remain queued) - TestSendVSCPacketsToChainV2WithHandler: Verifies packets are sent correctly via the mock handler and deleted after successful send These tests verify the v2 packet sending path works correctly with the IBCPacketHandler interface.

Add v2 version of provider info query that works with client-based routing: - GetProviderInfoV2: Returns provider info using client ID instead of channel/connection (which don't exist in IBC v2 Eureka model) - QueryProviderInfo: Updated to try v2 first, then fall back to v1 for backward compatibility This allows consumers using IBC v2 to query provider information even without channel-based connections.

Add comprehensive integration tests for IBC v2 functionality: Provider tests (ibc_v2_integration_test.go): - TestIBCV2FullVSCFlow: Complete VSC packet flow with mock handler - TestIBCV2MultipleConsumers: Sending to multiple consumers - TestIBCV2ConsumerRemovalOnTimeout: Timeout triggers removal - TestIBCV2ConsumerRemovalOnErrorAck: Error ack triggers removal - TestIBCV2DualModeRouting: v2 routing when no channel exists Consumer tests (ibc_v2_integration_test.go): - TestIBCV2ConsumerFullVSCFlow: Complete VSC reception flow - TestIBCV2ConsumerOutOfOrderHandling: Late packets ignored - TestIBCV2ConsumerRejectsUnknownProvider: Security validation - TestIBCV2ConsumerProviderInfoQuery: v2 query support - TestIBCV2ConsumerDuplicatePacketHandling: Duplicate rejection These tests verify end-to-end IBC v2 behavior including edge cases.

Add documentation for IBC v2 (Eureka) support: - Feature comparison table (v1 vs v2) - IBC v2 benefits (simpler setup, out-of-order handling) - Integration code example for app wiring - Application IDs (vaas/provider, vaas/consumer) This helps users understand and integrate IBC v2 routing.

Add comprehensive documentation for IBC v2 (Eureka) support: - API reference with all queries and messages - Deployment guide for provider and consumer chains - Example configurations for genesis and messages - Updated proto comments for IBC v2 compatibility notes

Added //nolint:staticcheck for GetTemplateClient (left for compatibility reasons) since TemplateClient is deprecated

…istration flows

clients at launch

tbruyelle · 2026-04-15T12:09:25Z

@julienrbrt do your latest changes still match the points listed in the PR body ? If not please add some comments, thanks!

julienrbrt · 2026-04-15T12:32:17Z

@julienrbrt do your latest changes still match the points listed in the PR body ? If not please add some comments, thanks!

asked an llm to do it. pretty good summary.
what was scary is that it used gh pr edit without asking me 🤯

tbruyelle · 2026-04-15T13:32:26Z

without asking me

waaat

clockworkgr added 22 commits February 4, 2026 21:11

feat(ibc): add IBC v2 deprecation notes to provider proto

ea27723

- Mark template_client as deprecated (per-consumer config recommended) - Add IBC v2 note to connection_id field - Regenerate proto files

feat(ibc): regenerate mocks with IBCPacketHandler interface

924dadf

Regenerate test mocks to include the new IBCPacketHandler interface added for IBC v2 packet sending. This interface provides a clean abstraction for packet sending that can be used with both v1 and v2.

test: add HighestValsetUpdateID test for IBC v2 out-of-order handling

3f547e4

Add test for the HighestValsetUpdateID getter/setter which is used in IBC v2 to track the highest processed valset update ID for out-of-order packet handling.

chore: Minor lint fixes

a1e7063

Added //nolint:staticcheck for GetTemplateClient (left for compatibility reasons) since TemplateClient is deprecated

fix: Leave go.mod / Dep versions untouched for now

56844dd

fix: Add client validation to CreateConsumer and improve/document reg…

011afec

…istration flows

Merge branch 'main' into feat/ibcv2

f81fce1

julienrbrt self-requested a review February 9, 2026 17:05

Pantani reviewed Feb 10, 2026

View reviewed changes

Comment thread x/vaas/provider/ibc_module_v2.go Outdated

Comment thread x/vaas/provider/ibc_module_v2.go Outdated

Comment thread x/vaas/provider/ibc_module_v2.go Outdated

Comment thread x/vaas/provider/ibc_module_v2.go Outdated

julienrbrt mentioned this pull request Feb 26, 2026

feat: wire vaas provider atomone-hub/atomone#283

Draft

Merge branch 'main' into feat/ibcv2

a866c3e

julienrbrt requested review from giuliostramondo, giunatale and tbruyelle as code owners March 3, 2026 10:28

fix go.mod

6fb95c5

cleanup old commands

6b6ca4f

julienrbrt reviewed Apr 13, 2026

View reviewed changes

Comment thread x/vaas/provider/keeper/relay.go Outdated

julienrbrt added 5 commits April 13, 2026 15:24

remove counterparty hack

2e82ee4

cleanup docs

ed20cd8

clean helpers

c096da1

no cached tests

afc45e2

re-add hack merkle fix

e89d9a0

julienrbrt marked this pull request as ready for review April 13, 2026 18:21

julienrbrt marked this pull request as draft April 14, 2026 07:45

refactor: improve consumer validation to trust IBC v2 and auto-create

fd86b5f

clients at launch

julienrbrt marked this pull request as ready for review April 14, 2026 09:22

julienrbrt requested a review from tbruyelle April 14, 2026 09:26

julienrbrt approved these changes Apr 14, 2026

View reviewed changes

tbruyelle reviewed Apr 15, 2026

View reviewed changes

Comment thread proto/vaas/consumer/v1/genesis.proto Outdated

fix: proto field numbers

9abce8e

tbruyelle reviewed Apr 15, 2026

View reviewed changes

Comment thread x/vaas/provider/keeper/relay.go

tbruyelle reviewed Apr 15, 2026

View reviewed changes

Comment thread x/vaas/provider/keeper/params.go

tbruyelle reviewed Apr 15, 2026

View reviewed changes

Comment thread x/vaas/provider/keeper/keeper.go Outdated

julienrbrt added 5 commits April 15, 2026 18:22

add v2 keeper interface

72993a9

add comment

e08887b

switch client when fronzen/expired

2947c8d

update deps

4ea2132

fix first time connection

b4539cb

julienrbrt requested a review from tbruyelle April 16, 2026 12:12

tbruyelle approved these changes Apr 16, 2026

View reviewed changes

julienrbrt merged commit 1b107de into main Apr 16, 2026
4 checks passed

julienrbrt mentioned this pull request Apr 17, 2026

refactor: separate client creation from consumer launch #30

Merged

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

feat: IBC v2 support#18

feat: IBC v2 support#18
julienrbrt merged 64 commits intomainfrom
feat/ibcv2

clockworkgr commented Feb 5, 2026 •

edited by julienrbrt

Loading

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

tbruyelle commented Apr 15, 2026

Uh oh!

julienrbrt commented Apr 15, 2026

Uh oh!

tbruyelle commented Apr 15, 2026

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

Conversation

clockworkgr commented Feb 5, 2026 • edited by julienrbrt Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Key changes

Proto field renumbering

Assumptions

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

tbruyelle commented Apr 15, 2026

Uh oh!

julienrbrt commented Apr 15, 2026

Uh oh!

tbruyelle commented Apr 15, 2026

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

clockworkgr commented Feb 5, 2026 •

edited by julienrbrt

Loading