ibchooks

package
v2.0.4 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Mar 28, 2024 License: Apache-2.0 Imports: 24 Imported by: 0

README

IBC-hooks

Taken from osmosis v14.0.0-rc1 (commit 26e2fad8e7b3eb7c33965360b31a593b392d7d75)

Removed ibc_callback functionality since we already have similar sudo callback mechanism in Transfer module.

Module https://github.com/osmosis-labs/osmosis/tree/v14.0.0-rc1/x/ibc-hooks

Wasm Hooks

The wasm hook is an IBC middleware which is used to allow ICS-20 token transfers to initiate contract calls. This allows cross-chain contract calls, that involve token movement. This is useful for a variety of usecases. One of primary importance is cross-chain swaps, which is an extremely powerful primitive.

The mechanism enabling this is a memo field on every ICS20 transfer packet as of IBC v3.4.0. Wasm hooks is an IBC middleware that parses an ICS20 transfer, and if the memo field is of a particular form, executes a wasm contract call. We now detail the memo format for wasm contract calls, and the execution guarantees provided.

Cosmwasm Contract Execution Format

Before we dive into the IBC metadata format, we show the cosmwasm execute message format, so the reader has a sense of what are the fields we need to be setting in. The cosmwasm MsgExecuteContract is defined here as the following type:

type MsgExecuteContract struct {
// Sender is the that actor that signed the messages
Sender string
// Contract is the address of the smart contract
Contract string
// Msg json encoded message to be passed to the contract
Msg RawContractMessage
// Funds coins that are transferred to the contract on execution
Funds sdk.Coins
}

So we detail where we want to get each of these fields from:

  • Sender: We cannot trust the sender of an IBC packet, the counterparty chain has full ability to lie about it. We cannot risk this sender being confused for a particular user or module address on Neutron. So we replace the sender with an account to represent the sender prefixed by the channel and a wasm module prefix. This is done by setting the sender to Bech32(Hash("ibc-wasm-hook-intermediaryg" || channelID || sender)), where the channelId is the channel id on the local chain.
  • Contract: This field should be directly obtained from the ICS-20 packet metadata
  • Msg: This field should be directly obtained from the ICS-20 packet metadata.
  • Funds: This field is set to the amount of funds being sent over in the ICS 20 packet. One detail is that the denom in the packet is the counterparty chains representation of the denom, so we have to translate it to Neutron' representation.

So our constructed cosmwasm message that we execute will look like:

msg := MsgExecuteContract{
	// Sender is the that actor that signed the messages
	Sender: "ntrn-hash-of-channel-and-sender",
	// Contract is the address of the smart contract
	Contract: packet.data.memo["wasm"]["ContractAddress"],
	// Msg json encoded message to be passed to the contract
	Msg: packet.data.memo["wasm"]["Msg"],
	// Funds coins that are transferred to the contract on execution
	Funds: sdk.NewCoin{Denom: ibc.ConvertSenderDenomToLocalDenom(packet.data.Denom), Amount: packet.data.Amount}
}
ICS20 packet structure

So given the details above, we propagate the implied ICS20 packet data structure. ICS20 is JSON native, so we use JSON for the memo format.

{
    //... other ibc fields that we don't care about
    "data":{
    	"denom": "denom on counterparty chain (e.g. uatom)",  // will be transformed to the local denom (ibc/...)
        "amount": "1000",
        "sender": "addr on counterparty chain", // will be transformed
        "receiver": "contract addr or blank",
    	"memo": {
           "wasm": {
              "contract": "ntrnContractAddr",
              "msg": {
                "raw_message_fields": "raw_message_data",
              }
            }
        }
    }
}

An ICS20 packet is formatted correctly for wasmhooks iff the following all hold:

  • memo is not blank
  • memo is valid JSON
  • memo has at least one key, with value "wasm"
  • memo["wasm"] has exactly two entries, "contract" and "msg"
  • memo["wasm"]["msg"] is a valid JSON object
  • receiver == "" || receiver == memo["wasm"]["contract"]

We consider an ICS20 packet as directed towards wasmhooks iff all of the following hold:

  • memo is not blank
  • memo is valid JSON
  • memo has at least one key, with name "wasm"

If an ICS20 packet is not directed towards wasmhooks, wasmhooks doesn't do anything. If an ICS20 packet is directed towards wasmhooks, and is formatted incorrectly, then wasmhooks returns an error.

Execution flow

Pre wasm hooks:

  • Ensure the incoming IBC packet is cryptographically valid
  • Ensure the incoming IBC packet is not timed out.

In Wasm hooks, pre packet execution:

  • Ensure the packet is correctly formatted (as defined above)
  • Edit the receiver to be the hardcoded IBC module account

In wasm hooks, post packet execution:

  • Construct wasm message as defined before
  • Execute wasm message
  • if wasm message has error, return ErrAck
  • otherwise continue through middleware

Testing strategy

See go tests.

Documentation

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

This section is empty.

Types

type AppModule

type AppModule struct {
	AppModuleBasic
	// contains filtered or unexported fields
}

AppModule implements an application module for the ibc-hooks module.

func NewAppModule

func NewAppModule(ak types.AccountKeeper) AppModule

NewAppModule creates a new AppModule object.

func (AppModule) BeginBlock

func (am AppModule) BeginBlock(_ sdk.Context, _ abci.RequestBeginBlock)

BeginBlock returns the begin blocker for the ibc-hooks module.

func (AppModule) ConsensusVersion

func (AppModule) ConsensusVersion() uint64

ConsensusVersion implements AppModule/ConsensusVersion.

func (AppModule) EndBlock

EndBlock returns the end blocker for the ibc-hooks module. It returns no validator updates.

func (AppModule) ExportGenesis

func (am AppModule) ExportGenesis(_ sdk.Context, _ codec.JSONCodec) json.RawMessage

func (AppModule) InitGenesis

InitGenesis performs genesis initialization for the ibc-hooks module. It returns no validator updates.

func (AppModule) IsAppModule

func (am AppModule) IsAppModule()

IsAppModule implements the appmodule.AppModule interface.

func (AppModule) IsOnePerModuleType

func (am AppModule) IsOnePerModuleType()

IsOnePerModuleType implements the depinject.OnePerModuleType interface.

func (AppModule) Name

func (AppModule) Name() string

Name returns the ibc-hooks module's name.

func (AppModule) QuerierRoute

func (AppModule) QuerierRoute() string

QuerierRoute returns the module's querier route name.

func (AppModule) RegisterInvariants

func (am AppModule) RegisterInvariants(_ sdk.InvariantRegistry)

RegisterInvariants registers the ibc-hooks module invariants.

func (AppModule) RegisterServices

func (am AppModule) RegisterServices(_ module.Configurator)

RegisterServices registers a gRPC query service to respond to the module-specific gRPC queries.

type AppModuleBasic

type AppModuleBasic struct{}

AppModuleBasic defines the basic application module used by the ibc-hooks module.

func (AppModuleBasic) DefaultGenesis

func (AppModuleBasic) DefaultGenesis(_ codec.JSONCodec) json.RawMessage

DefaultGenesis returns default genesis state as raw bytes for the module.

func (AppModuleBasic) GetQueryCmd

func (AppModuleBasic) GetQueryCmd() *cobra.Command

GetQueryCmd returns the root query command for the ibc-hooks module.

func (AppModuleBasic) GetTxCmd

func (AppModuleBasic) GetTxCmd() *cobra.Command

GetTxCmd returns no root tx command for the ibc-hooks module.

func (AppModuleBasic) Name

func (AppModuleBasic) Name() string

Name returns the ibc-hooks module's name.

func (AppModuleBasic) RegisterGRPCGatewayRoutes

func (AppModuleBasic) RegisterGRPCGatewayRoutes(_ client.Context, _ *runtime.ServeMux)

RegisterGRPCGatewayRoutes registers the gRPC Gateway routes for the ibc-hooks module.

func (AppModuleBasic) RegisterInterfaces

func (b AppModuleBasic) RegisterInterfaces(_ cdctypes.InterfaceRegistry)

RegisterInterfaces registers the module's interface types.

func (AppModuleBasic) RegisterLegacyAminoCodec

func (AppModuleBasic) RegisterLegacyAminoCodec(_ *codec.LegacyAmino)

RegisterLegacyAminoCodec registers the ibc-hooks module's types on the given LegacyAmino codec.

func (AppModuleBasic) RegisterRESTRoutes

func (AppModuleBasic) RegisterRESTRoutes(_ client.Context, _ *mux.Router)

RegisterRESTRoutes registers the REST routes for the ibc-hooks module.

func (AppModuleBasic) ValidateGenesis

ValidateGenesis performs genesis state validation for the ibc-hooks module.

type ContractAck

type ContractAck struct {
	ContractResult []byte `json:"contract_result"`
	IbcAck         []byte `json:"ibc_ack"`
}

type GetAppVersionAfterHooks

type GetAppVersionAfterHooks interface {
	GetAppVersionAfterHook(ctx sdk.Context, portID, channelID, result string, success bool)
}

type GetAppVersionBeforeHooks

type GetAppVersionBeforeHooks interface {
	GetAppVersionBeforeHook(ctx sdk.Context, portID, channelID string)
}

type GetAppVersionOverrideHooks

type GetAppVersionOverrideHooks interface {
	GetAppVersionOverride(i ICS4Middleware, ctx sdk.Context, portID, channelID string) (string, bool)
}

GetAppVersion Hooks

type Hooks

type Hooks interface{}

type IBCMiddleware

type IBCMiddleware struct {
	App            porttypes.IBCModule
	ICS4Middleware *ICS4Middleware
}

func NewIBCMiddleware

func NewIBCMiddleware(app porttypes.IBCModule, ics4 *ICS4Middleware) IBCMiddleware

func (IBCMiddleware) GetAppVersion

func (im IBCMiddleware) GetAppVersion(ctx sdk.Context, portID, channelID string) (string, bool)

func (IBCMiddleware) OnAcknowledgementPacket

func (im IBCMiddleware) OnAcknowledgementPacket(
	ctx sdk.Context,
	packet channeltypes.Packet,
	acknowledgement []byte,
	relayer sdk.AccAddress,
) error

OnAcknowledgementPacket implements the IBCMiddleware interface

func (IBCMiddleware) OnChanCloseConfirm

func (im IBCMiddleware) OnChanCloseConfirm(
	ctx sdk.Context,
	portID,
	channelID string,
) error

OnChanCloseConfirm implements the IBCMiddleware interface

func (IBCMiddleware) OnChanCloseInit

func (im IBCMiddleware) OnChanCloseInit(
	ctx sdk.Context,
	portID,
	channelID string,
) error

OnChanCloseInit implements the IBCMiddleware interface

func (IBCMiddleware) OnChanOpenAck

func (im IBCMiddleware) OnChanOpenAck(
	ctx sdk.Context,
	portID,
	channelID string,
	counterpartyChannelID string,
	counterpartyVersion string,
) error

OnChanOpenAck implements the IBCMiddleware interface

func (IBCMiddleware) OnChanOpenConfirm

func (im IBCMiddleware) OnChanOpenConfirm(
	ctx sdk.Context,
	portID,
	channelID string,
) error

OnChanOpenConfirm implements the IBCMiddleware interface

func (IBCMiddleware) OnChanOpenInit

func (im IBCMiddleware) OnChanOpenInit(
	ctx sdk.Context,
	order channeltypes.Order,
	connectionHops []string,
	portID string,
	channelID string,
	channelCap *capabilitytypes.Capability,
	counterparty channeltypes.Counterparty,
	version string,
) (string, error)

OnChanOpenInit implements the IBCMiddleware interface

func (IBCMiddleware) OnChanOpenTry

func (im IBCMiddleware) OnChanOpenTry(
	ctx sdk.Context,
	order channeltypes.Order,
	connectionHops []string,
	portID,
	channelID string,
	channelCap *capabilitytypes.Capability,
	counterparty channeltypes.Counterparty,
	counterpartyVersion string,
) (string, error)

OnChanOpenTry implements the IBCMiddleware interface

func (IBCMiddleware) OnRecvPacket

func (im IBCMiddleware) OnRecvPacket(
	ctx sdk.Context,
	packet channeltypes.Packet,
	relayer sdk.AccAddress,
) ibcexported.Acknowledgement

OnRecvPacket implements the IBCMiddleware interface

func (IBCMiddleware) OnTimeoutPacket

func (im IBCMiddleware) OnTimeoutPacket(
	ctx sdk.Context,
	packet channeltypes.Packet,
	relayer sdk.AccAddress,
) error

OnTimeoutPacket implements the IBCMiddleware interface

func (IBCMiddleware) SendPacket

func (im IBCMiddleware) SendPacket(
	ctx sdk.Context, channelCap *capabilitytypes.Capability, sourcePort, sourceChannel string, timeoutHeight clienttypes.Height, timeoutTimestamp uint64, data []byte,
) (sequence uint64, err error)

SendPacket implements the ICS4 Wrapper interface

func (IBCMiddleware) WriteAcknowledgement

func (im IBCMiddleware) WriteAcknowledgement(
	ctx sdk.Context,
	chanCap *capabilitytypes.Capability,
	packet ibcexported.PacketI,
	ack ibcexported.Acknowledgement,
) error

WriteAcknowledgement implements the ICS4 Wrapper interface

type ICS4Middleware

type ICS4Middleware struct {

	// Hooks
	Hooks Hooks
	// contains filtered or unexported fields
}

func NewICS4Middleware

func NewICS4Middleware(channelKeeper types.ChannelKeeper, channel porttypes.ICS4Wrapper, hooks Hooks) ICS4Middleware

func (ICS4Middleware) GetAppVersion

func (i ICS4Middleware) GetAppVersion(ctx sdk.Context, portID, channelID string) (string, bool)

func (ICS4Middleware) SendPacket

func (i ICS4Middleware) SendPacket(ctx sdk.Context, channelCap *capabilitytypes.Capability, sourcePort, sourceChannel string, timeoutHeight clienttypes.Height, timeoutTimestamp uint64, data []byte) (sequence uint64, err error)

func (ICS4Middleware) WriteAcknowledgement

func (i ICS4Middleware) WriteAcknowledgement(ctx sdk.Context, chanCap *capabilitytypes.Capability, packet ibcexported.PacketI, ack ibcexported.Acknowledgement) error

type OnAcknowledgementPacketAfterHooks

type OnAcknowledgementPacketAfterHooks interface {
	OnAcknowledgementPacketAfterHook(ctx sdk.Context, packet channeltypes.Packet, acknowledgement []byte, relayer sdk.AccAddress, err error)
}

type OnAcknowledgementPacketBeforeHooks

type OnAcknowledgementPacketBeforeHooks interface {
	OnAcknowledgementPacketBeforeHook(ctx sdk.Context, packet channeltypes.Packet, acknowledgement []byte, relayer sdk.AccAddress)
}

type OnAcknowledgementPacketOverrideHooks

type OnAcknowledgementPacketOverrideHooks interface {
	OnAcknowledgementPacketOverride(im IBCMiddleware, ctx sdk.Context, packet channeltypes.Packet, acknowledgement []byte, relayer sdk.AccAddress) error
}

OnAcknowledgementPacket Hooks

type OnChanCloseConfirmAfterHooks

type OnChanCloseConfirmAfterHooks interface {
	OnChanCloseConfirmAfterHook(ctx sdk.Context, portID, channelID string, err error)
}

type OnChanCloseConfirmBeforeHooks

type OnChanCloseConfirmBeforeHooks interface {
	OnChanCloseConfirmBeforeHook(ctx sdk.Context, portID, channelID string)
}

type OnChanCloseConfirmOverrideHooks

type OnChanCloseConfirmOverrideHooks interface {
	OnChanCloseConfirmOverride(im IBCMiddleware, ctx sdk.Context, portID, channelID string) error
}

OnChanCloseConfirm Hooks

type OnChanCloseInitAfterHooks

type OnChanCloseInitAfterHooks interface {
	OnChanCloseInitAfterHook(ctx sdk.Context, portID, channelID string, err error)
}

type OnChanCloseInitBeforeHooks

type OnChanCloseInitBeforeHooks interface {
	OnChanCloseInitBeforeHook(ctx sdk.Context, portID, channelID string)
}

type OnChanCloseInitOverrideHooks

type OnChanCloseInitOverrideHooks interface {
	OnChanCloseInitOverride(im IBCMiddleware, ctx sdk.Context, portID, channelID string) error
}

OnChanCloseInit Hooks

type OnChanOpenAckAfterHooks

type OnChanOpenAckAfterHooks interface {
	OnChanOpenAckAfterHook(ctx sdk.Context, portID, channelID, counterpartyChannelID, counterpartyVersion string, err error)
}

type OnChanOpenAckBeforeHooks

type OnChanOpenAckBeforeHooks interface {
	OnChanOpenAckBeforeHook(ctx sdk.Context, portID, channelID, counterpartyChannelID, counterpartyVersion string)
}

type OnChanOpenAckOverrideHooks

type OnChanOpenAckOverrideHooks interface {
	OnChanOpenAckOverride(im IBCMiddleware, ctx sdk.Context, portID, channelID, counterpartyChannelID, counterpartyVersion string) error
}

OnChanOpenAck Hooks

type OnChanOpenConfirmAfterHooks

type OnChanOpenConfirmAfterHooks interface {
	OnChanOpenConfirmAfterHook(ctx sdk.Context, portID, channelID string, err error)
}

type OnChanOpenConfirmBeforeHooks

type OnChanOpenConfirmBeforeHooks interface {
	OnChanOpenConfirmBeforeHook(ctx sdk.Context, portID, channelID string)
}

type OnChanOpenConfirmOverrideHooks

type OnChanOpenConfirmOverrideHooks interface {
	OnChanOpenConfirmOverride(im IBCMiddleware, ctx sdk.Context, portID, channelID string) error
}

OnChanOpenConfirm Hooks

type OnChanOpenInitAfterHooks

type OnChanOpenInitAfterHooks interface {
	OnChanOpenInitAfterHook(ctx sdk.Context, order channeltypes.Order, connectionHops []string, portID, channelID string, channelCap *capabilitytypes.Capability, counterparty channeltypes.Counterparty, version, finalVersion string, err error)
}

type OnChanOpenInitBeforeHooks

type OnChanOpenInitBeforeHooks interface {
	OnChanOpenInitBeforeHook(ctx sdk.Context, order channeltypes.Order, connectionHops []string, portID, channelID string, channelCap *capabilitytypes.Capability, counterparty channeltypes.Counterparty, version string)
}

type OnChanOpenInitOverrideHooks

type OnChanOpenInitOverrideHooks interface {
	OnChanOpenInitOverride(im IBCMiddleware, ctx sdk.Context, order channeltypes.Order, connectionHops []string, portID, channelID string, channelCap *capabilitytypes.Capability, counterparty channeltypes.Counterparty, version string) (string, error)
}

type OnChanOpenTryAfterHooks

type OnChanOpenTryAfterHooks interface {
	OnChanOpenTryAfterHook(ctx sdk.Context, order channeltypes.Order, connectionHops []string, portID, channelID string, channelCap *capabilitytypes.Capability, counterparty channeltypes.Counterparty, counterpartyVersion, version string, err error)
}

type OnChanOpenTryBeforeHooks

type OnChanOpenTryBeforeHooks interface {
	OnChanOpenTryBeforeHook(ctx sdk.Context, order channeltypes.Order, connectionHops []string, portID, channelID string, channelCap *capabilitytypes.Capability, counterparty channeltypes.Counterparty, counterpartyVersion string)
}

type OnChanOpenTryOverrideHooks

type OnChanOpenTryOverrideHooks interface {
	OnChanOpenTryOverride(im IBCMiddleware, ctx sdk.Context, order channeltypes.Order, connectionHops []string, portID, channelID string, channelCap *capabilitytypes.Capability, counterparty channeltypes.Counterparty, counterpartyVersion string) (string, error)
}

OnChanOpenTry Hooks

type OnRecvPacketAfterHooks

type OnRecvPacketAfterHooks interface {
	OnRecvPacketAfterHook(ctx sdk.Context, packet channeltypes.Packet, relayer sdk.AccAddress, ack ibcexported.Acknowledgement)
}

type OnRecvPacketBeforeHooks

type OnRecvPacketBeforeHooks interface {
	OnRecvPacketBeforeHook(ctx sdk.Context, packet channeltypes.Packet, relayer sdk.AccAddress)
}

type OnRecvPacketOverrideHooks

type OnRecvPacketOverrideHooks interface {
	OnRecvPacketOverride(im IBCMiddleware, ctx sdk.Context, packet channeltypes.Packet, relayer sdk.AccAddress) ibcexported.Acknowledgement
}

OnRecvPacket Hooks

type OnTimeoutPacketAfterHooks

type OnTimeoutPacketAfterHooks interface {
	OnTimeoutPacketAfterHook(ctx sdk.Context, packet channeltypes.Packet, relayer sdk.AccAddress, err error)
}

type OnTimeoutPacketBeforeHooks

type OnTimeoutPacketBeforeHooks interface {
	OnTimeoutPacketBeforeHook(ctx sdk.Context, packet channeltypes.Packet, relayer sdk.AccAddress)
}

type OnTimeoutPacketOverrideHooks

type OnTimeoutPacketOverrideHooks interface {
	OnTimeoutPacketOverride(im IBCMiddleware, ctx sdk.Context, packet channeltypes.Packet, relayer sdk.AccAddress) error
}

OnTimeoutPacket Hooks

type SendPacketAfterHooks

type SendPacketAfterHooks interface {
	SendPacketAfterHook(ctx sdk.Context, chanCap *capabilitytypes.Capability, packet ibcexported.PacketI, err error)
}

type SendPacketBeforeHooks

type SendPacketBeforeHooks interface {
	SendPacketBeforeHook(ctx sdk.Context, chanCap *capabilitytypes.Capability, packet ibcexported.PacketI)
}

type SendPacketOverrideHooks

type SendPacketOverrideHooks interface {
	SendPacketOverride(i ICS4Middleware, ctx sdk.Context, chanCap *capabilitytypes.Capability, packet ibcexported.PacketI) error
}

SendPacket Hooks

type WasmHooks

type WasmHooks struct {
	ContractKeeper *wasmkeeper.Keeper
	// contains filtered or unexported fields
}

func NewWasmHooks

func NewWasmHooks(contractKeeper *wasmkeeper.Keeper, bech32PrefixAccAddr string) WasmHooks

func (WasmHooks) OnRecvPacketOverride

func (h WasmHooks) OnRecvPacketOverride(im IBCMiddleware, ctx sdk.Context, packet channeltypes.Packet, relayer sdk.AccAddress) ibcexported.Acknowledgement

func (WasmHooks) ProperlyConfigured

func (h WasmHooks) ProperlyConfigured() bool

type WriteAcknowledgementAfterHooks

type WriteAcknowledgementAfterHooks interface {
	WriteAcknowledgementAfterHook(ctx sdk.Context, chanCap *capabilitytypes.Capability, packet ibcexported.PacketI, ack ibcexported.Acknowledgement, err error)
}

type WriteAcknowledgementBeforeHooks

type WriteAcknowledgementBeforeHooks interface {
	WriteAcknowledgementBeforeHook(ctx sdk.Context, chanCap *capabilitytypes.Capability, packet ibcexported.PacketI, ack ibcexported.Acknowledgement)
}

type WriteAcknowledgementOverrideHooks

type WriteAcknowledgementOverrideHooks interface {
	WriteAcknowledgementOverride(i ICS4Middleware, ctx sdk.Context, chanCap *capabilitytypes.Capability, packet ibcexported.PacketI, ack ibcexported.Acknowledgement) error
}

WriteAcknowledgement Hooks

Directories

Path Synopsis
client
cli

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL