IBC Hooks

x/ibc-hooks/.cargo/config

@@ -0,0 +1,2 @@
+[alias]
+wasm = "build --release --lib --target wasm32-unknown-unknown"

x/ibc-hooks/README.md

@@ -0,0 +1,185 @@
+# 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](https://medium.com/the-interchain-foundation/moving-beyond-simple-token-transfers-d42b2b1dc29b).
+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](https://github.com/CosmWasm/wasmd/blob/4fe2fbc8f322efdaf187e2e5c99ce32fd1df06f0/x/wasm/types/tx.pb.go#L340-L349
+) as the following type:
+
+```go
+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 Osmosis.
+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-intermediary" || 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 Osmosis' representation.
+
+So our constructed cosmwasm message that we execute will look like:
+
+```go
+msg := MsgExecuteContract{
+	// Sender is the that actor that signed the messages
+	Sender: "osmo1-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 propogate the implied ICS20 packet data structure.
+ICS20 is JSON native, so we use JSON for the memo format.
+
+```json 
+{
+    //... 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": "osmo1contractAddr",
+              "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 formated incorrectly, then wasmhooks returns an error.
+
+### Execution flow
+
+Pre wasm hooks:
+
+* Ensure the incoming IBC packet is cryptogaphically 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
+
+## Ack callbacks
+
+A contract that sends an IBC transfer, may need to listen for the ACK from that packet. To allow
+contracts to listen on the ack of specific packets, we provide Ack callbacks. 
+
+### Design
+
+The sender of an IBC transfer packet may specify a callback for when the ack of that packet is received in the memo 
+field of the transfer packet. 
+
+Crucially, _only_ the IBC packet sender can set the callback.
+
+### Use case
+
+The crosschain swaps implementation sends an IBC transfer. If the transfer were to fail, we want to allow the sender
+to be able to retrieve their funds (which would otherwise be stuck in the contract). To do this, we allow users to 
+retrieve the funds after the timeout has passed, but without the ack information, we cannot guarantee that the send 
+hasn't failed (i.e.: returned an error ack notifying that the receiving change didn't accept it)
+
+### Implementation
+
+#### Callback information in memo
+
+For the callback to be processed, the transfer packet's memo should contain the following in its JSON:
+
+`{"ibc_callback": "osmo1contractAddr"}`
+
+The wasm hooks will keep the mapping from the packet's channel and sequence to the contract in storage. When an ack is
+received, it will notify the specified contract via a sudo message.
+
+#### Interface for receiving the Acks and Timeouts
+
+The contract that awaits the callback should implement the following interface for a sudo message:
+
+```rust
+#[cw_serde]
+pub enum IBCLifecycleComplete {
+    #[serde(rename = "ibc_ack")]
+    IBCAck {
+        /// The source channel (osmosis side) of the IBC packet
+        channel: String,
+        /// The sequence number that the packet was sent with
+        sequence: u64,
+        /// String encoded version of the ack as seen by OnAcknowledgementPacket(..)
+        ack: String,
+        /// Weather an ack is a success of failure according to the transfer spec
+        success: bool,
+    },
+    #[serde(rename = "ibc_timeout")]
+    IBCTimeout {
+        /// The source channel (osmosis side) of the IBC packet
+        channel: String,
+        /// The sequence number that the packet was sent with
+        sequence: u64,
+    },
+}
+
+/// Message type for `sudo` entry_point
+#[cw_serde]
+pub enum SudoMsg {
+    #[serde(rename = "ibc_lifecycle_complete")]
+    IBCLifecycleComplete(IBCLifecycleComplete),
+}
+```
+
+# Testing strategy
+
+See go tests.

x/ibc-hooks/client/cli/query.go

@@ -0,0 +1,75 @@
+package cli
+
+import (
+	"fmt"
+	"github.com/cosmos/cosmos-sdk/client/flags"
+	sdk "github.com/cosmos/cosmos-sdk/types"
+	"github.com/cosmos/cosmos-sdk/version"
+	"github.com/osmosis-labs/osmosis/x/ibc-hooks/keeper"
+	"github.com/spf13/cobra"
+	"strings"
+
+	"github.com/osmosis-labs/osmosis/x/ibc-hooks/types"
+)
+
+func indexRunCmd(cmd *cobra.Command, args []string) error {
+	usageTemplate := `Usage:{{if .HasAvailableSubCommands}}
+  {{.CommandPath}} [command]{{end}}
+
+{{if .HasAvailableSubCommands}}Available Commands:{{range .Commands}}{{if .IsAvailableCommand}}
+  {{rpad .Name .NamePadding }} {{.Short}}{{end}}{{end}}
+
+Use "{{.CommandPath}} [command] --help" for more information about a command.{{end}}
+`
+	cmd.SetUsageTemplate(usageTemplate)
+	return cmd.Help()
+}
+
+// GetQueryCmd returns the cli query commands for this module.
+func GetQueryCmd() *cobra.Command {
+	cmd := &cobra.Command{
+		Use:                        types.ModuleName,
+		Short:                      fmt.Sprintf("Querying commands for the %s module", types.ModuleName),
+		DisableFlagParsing:         true,
+		SuggestionsMinimumDistance: 2,
+		RunE:                       indexRunCmd,
+	}
+
+	cmd.AddCommand(
+		GetCmdWasmSender(),
+	)
+	return cmd
+}
+
+// GetCmdPoolParams return pool params.
+func GetCmdWasmSender() *cobra.Command {
+	cmd := &cobra.Command{
+		Use:   "wasm-sender <channelID> <originalSender>",
+		Short: "Generate the local address for a wasm hooks sender",
+		Long: strings.TrimSpace(
+			fmt.Sprintf(`Generate the local address for a wasm hooks sender.
+Example:
+$ %s query ibc-hooks wasm-hooks-sender channel-42 juno12smx2wdlyttvyzvzg54y2vnqwq2qjatezqwqxu
+`,
+				version.AppName,
+			),
+		),
+		Args: cobra.ExactArgs(2),
+		RunE: func(cmd *cobra.Command, args []string) error {
+			channelID := args[0]
+			originalSender := args[1]
+			// ToDo: Make this flexible as an arg
+			prefix := sdk.GetConfig().GetBech32AccountAddrPrefix()
+			senderBech32, err := keeper.DeriveIntermediateSender(channelID, originalSender, prefix)
+			if err != nil {
+				return err
+			}
+			fmt.Println(senderBech32)
+			return nil
+		},
+	}
+
+	flags.AddQueryFlagsToCmd(cmd)
+
+	return cmd
+}