Merge pull request #92 from cosmos/aayushijain23/add-new-msg-type-delete

Implement new DeleteName Message Type

Author: hschoenburg

tutorial/README.md

@@ -64,22 +64,23 @@ Then, just follow along! The first step describes the design of your application
 1. [Design](./app-design.md) the application.
 2. Begin the implementation of your application in [`./app.go`](./app-init.md).
 3. Start building your module by defining some basic [`Types`](types.md).
-4. Define the keys needed for your module [`key`](./key.md)
-5. Create the main core of the module using the [`Keeper`](./keeper.md).
-6. Define state transitions through [`Msgs` and `Handlers`](./msgs-handlers.md).
+4. Define the keys needed for your module [`key`](./key.md).
+5. Define errors that are custom to your module [`Errors`](./errors.md).
+6. Create the main core of the module using the [`Keeper`](./keeper.md).
+7. Define state transitions through [`Msgs` and `Handlers`](./msgs-handlers.md).
    - [`SetName`](./set-name.md)
    - [`BuyName`](./buy-name.md)
-7. Make views on your state machine with [`Queriers`](./queriers.md).
-8. Create the [`alias file`](./alias.md)
-9. Register your types in the encoding format using [`sdk.Codec`](./codec.md).
-10. Create [CLI interactions for your module](./cli.md).
-11. Create [HTTP routes for clients to access your nameservice](./rest.md).
-12. Implement the [AppModule interface](./module.md)
-13. Configure your [Genesis state](./genesis.md).
-14. Import your module and [finish building your application](./app-complete.md)!
-15. Create the [`nsd` and `nscli` entry points](./entrypoint.md) to your application.
-16. Setup [dependency management using `go.mod`](./gomod.md).
-17. [Build and run](./build-run.md) the example.
-18. [Run REST routes](./run-rest.md).
+8. Make views on your state machine with [`Queriers`](./queriers.md).
+9. Create the [`alias file`](./alias.md)
+10. Register your types in the encoding format using [`sdk.Codec`](./codec.md).
+11. Create [CLI interactions for your module](./cli.md).
+12. Create [HTTP routes for clients to access your nameservice](./rest.md).
+13. Implement the [AppModule interface](./module.md)
+14. Configure your [Genesis state](./genesis.md).
+15. Import your module and [finish building your application](./app-complete.md)!
+16. Create the [`nsd` and `nscli` entry points](./entrypoint.md) to your application.
+17. Setup [dependency management using `go.mod`](./gomod.md).
+18. [Build and run](./build-run.md) the example.
+19. [Run REST routes](./run-rest.md).
 
 ## [Click here](./app-design.md) to get started with the tutorial!

tutorial/alias.md

@@ -28,11 +28,12 @@ const (
 
 ```go
 var (
-	NewMsgBuyName = types.NewMsgBuyName
-	NewMsgSetName = types.NewMsgSetName
-	NewWhois      = types.NewWhois
-	ModuleCdc     = types.ModuleCdc
-	RegisterCodec = types.RegisterCodec
+	NewMsgBuyName 	  = types.NewMsgBuyName
+	NewMsgSetName     = types.NewMsgSetName
+	NewMsgDeleteName  = types.NewMsgDeleteName
+	NewWhois      	  = types.NewWhois
+	ModuleCdc     	  = types.ModuleCdc
+	RegisterCodec 	  = types.RegisterCodec
 )
 ```
 
@@ -42,6 +43,7 @@ var (
 type (
 	MsgSetName      = types.MsgSetName
 	MsgBuyName      = types.MsgBuyName
+	MsgDeleteName   = types.MsgDeleteName
 	QueryResResolve = types.QueryResResolve
 	QueryResNames   = types.QueryResNames
 	Whois           = types.Whois

tutorial/build-run.md

@@ -95,6 +95,13 @@ nscli query nameservice whois jack.id
 
 # Alice buys name from jack
 nscli tx nameservice buy-name jack.id 10nametoken --from alice
+
+# Alice decides to delete the name she just bought from jack
+nscli tx nameservice delete-name jack.id --from alice
+
+# Try out a whois query against the name you just deleted
+nscli query nameservice whois jack.id
+# > {"value":"","owner":"","price":[{"denom":"nametoken","amount":"1"}]}
 ```
 
 ### Congratulations, you have built a Cosmos SDK application! This tutorial is now complete. If you want to see how to run the same commands using the REST server [click here](run-rest.md).

tutorial/buy-name.md

@@ -104,4 +104,5 @@ If either `SubtractCoins` or `SendCoins` returns a non-nil error, the handler th
 
 > _*NOTE*_: This handler uses functions from the `coinKeeper` to perform currency operations. If your application is performing currency operations you may want to take a look at the [godocs for this module](https://godoc.org/github.com/cosmos/cosmos-sdk/x/bank#BaseKeeper) to see what functions it exposes.
 
-### Now that you have your `Msgs` and `Handlers` defined it's time to learn about making the data from these transactions [available for querying](queriers.md)!
+### Great, now owners can `BuyName`s! But what if they don't want the name any longer? Your module needs a way for users to delete names! Let us define [define the `DeleteName` message](./delete-name.md).
+

tutorial/cli.md

@@ -149,6 +149,7 @@ func GetTxCmd(storeKey string, cdc *codec.Codec) *cobra.Command {
 	nameserviceTxCmd.AddCommand(client.PostCommands(
 		GetCmdBuyName(cdc),
 		GetCmdSetName(cdc),
+		GetCmdDeleteName(cdc),
 	)...)
 
 	return nameserviceTxCmd
@@ -208,6 +209,26 @@ func GetCmdSetName(cdc *codec.Codec) *cobra.Command {
 	}
 }
 
+// GetCmdDeleteName is the CLI command for sending a DeleteName transaction
+func GetCmdDeleteName(cdc *codec.Codec) *cobra.Command {
+	return &cobra.Command{
+		Use:   "delete-name [name]",
+		Short: "Delete the name that you own",
+		Args:  cobra.ExactArgs(1),
+		RunE: func(cmd *cobra.Command, args []string) error {
+			cliCtx := context.NewCLIContext().WithCodec(cdc).WithAccountDecoder(cdc)
+
+			txBldr := auth.NewTxBuilderFromCLI().WithTxEncoder(utils.GetTxEncoder(cdc))
+
+			msg := types.NewMsgDeleteName(args[0], cliCtx.GetFromAddress())
+			if err := msg.ValidateBasic(); err != nil {
+				return err
+			}
+
+			return utils.GenerateOrBroadcastMsgs(cliCtx, txBldr, []sdk.Msg{msg})
+		},
+	}
+}
 ```
 
 Notes on the above code:

tutorial/codec.md

@@ -1,6 +1,6 @@
 # Codec File
 
-To [register your types with Amino](https://github.com/tendermint/go-amino#registering-types) so that they can be encoded/decoded, there is a bit of code that needs to be placed in `./x/nameservice/types/codec.go`. Any interface you create and any struct that implements an interface needs to be declared in the `RegisterCodec` function. In this module the two `Msg` implementations (`SetName` and `BuyName`) need to be registered, but your `Whois` query return type does not. In addition, we define a module specific codec for use later.
+To [register your types with Amino](https://github.com/tendermint/go-amino#registering-types) so that they can be encoded/decoded, there is a bit of code that needs to be placed in `./x/nameservice/types/codec.go`. Any interface you create and any struct that implements an interface needs to be declared in the `RegisterCodec` function. In this module the three `Msg` implementations (`SetName`, `BuyName` and `DeleteName`) need to be registered, but your `Whois` query return type does not. In addition, we define a module specific codec for use later.
 
 ```go
 package types
@@ -19,6 +19,7 @@ func init() {
 func RegisterCodec(cdc *codec.Codec) {
 	cdc.RegisterConcrete(MsgSetName{}, "nameservice/SetName", nil)
 	cdc.RegisterConcrete(MsgBuyName{}, "nameservice/BuyName", nil)
+	cdc.RegisterConcrete(MsgDeleteName{}, "nameservice/DeleteName", nil)
 }
 ```
 

tutorial/delete-name.md

@@ -0,0 +1,89 @@
+# Delete Name
+
+## Msg
+
+Now it is time to define the `Msg` for deleting names and add it to the `./x/nameservice/types/msgs.go` file. This code is very similar to `SetName`:
+
+```go
+// MsgDeleteName defines a DeleteName message
+type MsgDeleteName struct {
+	Name  string         `json:"name"`
+	Owner sdk.AccAddress `json:"owner"`
+}
+
+// NewMsgDeleteName is a constructor function for MsgDeleteName
+func NewMsgDeleteName(name string, owner sdk.AccAddress) MsgDeleteName {
+	return MsgDeleteName{
+		Name:  name,
+		Owner: owner,
+	}
+}
+
+// Route should return the name of the module
+func (msg MsgDeleteName) Route() string { return RouterKey }
+
+// Type should return the action
+func (msg MsgDeleteName) Type() string { return "delete_name" }
+
+// ValidateBasic runs stateless checks on the message
+func (msg MsgDeleteName) ValidateBasic() sdk.Error {
+	if msg.Owner.Empty() {
+		return sdk.ErrInvalidAddress(msg.Owner.String())
+	}
+	if len(msg.Name) == 0 {
+		return sdk.ErrUnknownRequest("Name cannot be empty")
+	}
+	return nil
+}
+
+// GetSignBytes encodes the message for signing
+func (msg MsgDeleteName) GetSignBytes() []byte {
+	return sdk.MustSortJSON(ModuleCdc.MustMarshalJSON(msg))
+}
+
+// GetSigners defines whose signature is required
+func (msg MsgDeleteName) GetSigners() []sdk.AccAddress {
+	return []sdk.AccAddress{msg.Owner}
+}
+```
+
+Next, in the `./x/nameservice/handler.go` file, add the `MsgDeleteName` handler to the module router:
+
+```go
+// NewHandler returns a handler for "nameservice" type messages.
+func NewHandler(keeper Keeper) sdk.Handler {
+	return func(ctx sdk.Context, msg sdk.Msg) sdk.Result {
+		switch msg := msg.(type) {
+		case MsgSetName:
+			return handleMsgSetName(ctx, keeper, msg)
+		case MsgBuyName:
+			return handleMsgBuyName(ctx, keeper, msg)
+		case MsgDeleteName:
+			return handleMsgDeleteName(ctx, keeper, msg)
+		default:
+			errMsg := fmt.Sprintf("Unrecognized nameservice Msg type: %v", msg.Type())
+			return sdk.ErrUnknownRequest(errMsg).Result()
+		}
+	}
+}
+```
+
+Finally, define the `DeleteName` `handler` function which performs the state transitions triggered by the message. Keep in mind that at this point the message has had its `ValidateBasic` function run so there has been some input verification. However, `ValidateBasic` cannot query application state. Validation logic that is dependent on network state (e.g. account balances) should be performed in the `handler` function.
+
+```go
+// Handle a message to delete name
+func handleMsgDeleteName(ctx sdk.Context, keeper Keeper, msg MsgDeleteName) sdk.Result {
+	if !keeper.IsNamePresent(ctx, msg.Name) {
+		return types.ErrNameDoesNotExist(types.DefaultCodespace).Result()
+	}
+	if !msg.Owner.Equals(keeper.GetOwner(ctx, msg.Name)) { 
+		return sdk.ErrUnauthorized("Incorrect Owner").Result() 
+	}
+	keeper.DeleteWhois(ctx, msg.Name) 
+	return sdk.Result{}
+}
+```
+
+First check to see if the name currently exists in the store. If not, throw an error and return that to the user. Then check to see if the `Msg` sender is actually the owner of the name (`keeper.GetOwner`). If so, they can delete the name by calling the function on the `Keeper`. If not, throw an error and return that to the user.
+
+### Now that you have your `Msgs` and `Handlers` defined it's time to learn about making the data from these transactions [available for querying](queriers.md)!

tutorial/errors.md

@@ -0,0 +1,30 @@
+# Errors
+
+Start by creating a errors.go file within the types folder. Within your errors.go file, define errors that are custom to your module along with their codes.
+
+```go
+package types
+
+import (
+	sdk "github.com/cosmos/cosmos-sdk/types"
+)
+
+const (
+	DefaultCodespace sdk.CodespaceType = ModuleName
+
+	CodeNameDoesNotExist sdk.CodeType = 101
+)
+```
+
+Now it's time to add the corresponding method that'll be called at the time of error handling. For instance, let's say we try to delete a name that is not present in the store. In this case, an error should be thrown as the name does not exist.
+
+```go
+func ErrNameDoesNotExist(codespace sdk.CodespaceType) sdk.Error {
+	return sdk.NewError(codespace, CodeNameDoesNotExist, "Name does not exist")
+}
+```
+We'll see later on in the tutorial where this method is called.
+
+### Now we move on to writing the [Keeper for the module](./keeper.md).
+
+

tutorial/genesis.md

@@ -9,7 +9,6 @@ package nameservice
 
 import (
 	"fmt"
-
 	sdk "github.com/cosmos/cosmos-sdk/types"
 	abci "github.com/tendermint/tendermint/abci/types"
 )

tutorial/keeper.md

@@ -12,6 +12,7 @@ package nameservice
 import (
 	"github.com/cosmos/cosmos-sdk/codec"
 	"github.com/cosmos/cosmos-sdk/x/bank"
+	"github.com/cosmos/sdk-application-tutorial/x/nameservice/types"
 
 	sdk "github.com/cosmos/cosmos-sdk/types"
 )
@@ -66,7 +67,7 @@ Next, add a method to resolve the names (i.e. look up the `Whois` for the `name`
 // Gets the entire Whois metadata struct for a name
 func (k Keeper) GetWhois(ctx sdk.Context, name string) Whois {
 	store := ctx.KVStore(k.storeKey)
-	if !store.Has([]byte(name)) {
+	if !k.IsNamePresent(ctx, name) {
 		return NewWhois()
 	}
 	bz := store.Get([]byte(name))
@@ -80,6 +81,17 @@ Here, like in the `SetName` method, first access the store using the `StoreKey`.
 
 If a name currently does not exist in the store, it returns a new Whois, which has the minimumPrice initialized in it.
 
+Next, add a method to delete the names:
+
+```go
+// Deletes the entire Whois metadata struct for a name
+func (k Keeper) DeleteWhois(ctx sdk.Context, name string) {
+	store := ctx.KVStore(k.storeKey)
+	store.Delete([]byte(name))
+}
+```
+Here, like in the `SetName` method, first access the store using the `StoreKey`. Next, we delete the name from the store using its `.Delete([]byte)` method. As the store only takes `[]byte`, the `name` string is casted to `[]byte` while passing it as a function parameter.
+
 Now, we add functions for getting specific parameters from the store based on the name.  However, instead of rewriting the store getters and setters, we reuse the `GetWhois` and `SetWhois` functions.  For example, to set a field, first we grab the whole Whois data, update our specific field, and put the new version back into the store.
 
 ```go
@@ -123,6 +135,12 @@ func (k Keeper) SetPrice(ctx sdk.Context, name string, price sdk.Coins) {
 	whois.Price = price
 	k.SetWhois(ctx, name, whois)
 }
+
+// Check if the name is present in the store or not
+func (k Keeper) IsNamePresent(ctx sdk.Context, name string) bool {
+	store := ctx.KVStore(k.storeKey)
+	return store.Has([]byte(name))
+}
 ```
 
 The SDK also includes a feature called an `sdk.Iterator`, which returns an iterator over all the `<Key, Value>` pairs in a specific spot in a store.