12 KiB

Raw Blame History

Basecoin Example Plugin

In the previous tutorial, we saw how to start a Basecoin blockchain and use the CLI to send transactions. Here, we will demonstrate how to extend the blockchain and CLI to support a simple plugin.

Overview

Creating a new plugin and CLI to support it requires a little bit of boilerplate, but not much. For convenience, we've implemented an extremely simple example plugin that can be easily modified. The example is under docs/guide/src/example-plugin. To build your own plugin, copy this folder to a new location and start modifying it there.

Let's take a look at the files in docs/guide/src/example-plugin:

cmd.go
main.go
plugin.go

The main.go is very simple and does not need to be changed:

func main() {
	app := cli.NewApp()
	app.Name = "example-plugin"
	app.Usage = "example-plugin [command] [args...]"
	app.Version = "0.1.0"
	app.Commands = []cli.Command{
		commands.StartCmd,
		commands.TxCmd,
		commands.KeyCmd,
		commands.QueryCmd,
		commands.AccountCmd,
	}
	app.Run(os.Args)
}

It creates the CLI, exactly like the basecoin one. However, if we want our plugin to be active, we need to make sure it is registered with the application. In addition, if we want to send transactions to our plugin, we need to add a new command to the CLI. This is where the cmd.go comes in.

Commands

First, we register the plugin:

func init() {
	commands.RegisterTxSubcommand(ExamplePluginTxCmd)
	commands.RegisterStartPlugin("example-plugin", func() types.Plugin { return NewExamplePlugin() })
}

This creates a new subcommand under tx (defined below), and ensures the plugin is activated when we start the app. Now we actually define the new command:

var (
	ExampleFlag = cli.BoolFlag{
		Name:  "valid",
		Usage: "Set this to make the transaction valid",
	}

	ExamplePluginTxCmd = cli.Command{
		Name:  "example",
		Usage: "Create, sign, and broadcast a transaction to the example plugin",
		Action: func(c *cli.Context) error {
			return cmdExamplePluginTx(c)
		},
		Flags: append(commands.TxFlags, ExampleFlag),
	}
)

func cmdExamplePluginTx(c *cli.Context) error {
	exampleFlag := c.Bool("valid")
	exampleTx := ExamplePluginTx{exampleFlag}
	return commands.AppTx(c, "example-plugin", wire.BinaryBytes(exampleTx))
}

It's a simple command with one flag, which is just a boolean. However, it actually inherits more flags from the Basecoin framework:

Flags: append(commands.TxFlags, ExampleFlag),

The commands.TxFlags is defined in cmd/commands/tx.go:

var TxFlags = []cli.Flag{
	NodeFlag,
	ChainIDFlag,

	FromFlag,

	AmountFlag,
	CoinFlag,
	GasFlag,
	FeeFlag,
	SeqFlag,
}

It adds all the default flags for a Basecoin transaction.

If we now compile and run our program, we can see all the options:

cd $GOPATH/src/github.com/tendermint/basecoin
go install ./docs/guide/src/example-plugin
example-plugin tx example --help

The output:

NAME:
   example-plugin tx example - Create, sign, and broadcast a transaction to the example plugin

USAGE:
   example-plugin tx example [command options] [arguments...]

OPTIONS:
   --node value      Tendermint RPC address (default: "tcp://localhost:46657")
   --chain_id value  ID of the chain for replay protection (default: "test_chain_id")
   --from value      Path to a private key to sign the transaction (default: "key.json")
   --amount value    Coins to send in transaction of the format <amt><coin>,<amt2><coin2>,... (eg: 1btc,2gold,5silver)
   --gas value       The amount of gas for the transaction (default: 0)
   --fee value       Coins for the transaction fee of the format <amt><coin>
   --sequence value  Sequence number for the account (default: 0)
   --valid           Set this to make the transaction valid

Cool, eh?

Before we move on to plugin.go, let's look at the cmdExamplePluginTx function in cmd.go:

func cmdExamplePluginTx(c *cli.Context) error {
	exampleFlag := c.Bool("valid")
	exampleTx := ExamplePluginTx{exampleFlag}
	return commands.AppTx(c, "example-plugin", wire.BinaryBytes(exampleTx))
}

We read the flag from the CLI library, and then create the example transaction. Remember that Basecoin itself only knows about two transaction types, SendTx and AppTx. All plugin data must be serialized (ie. encoded as a byte-array) and sent as data in an AppTx. The commands.AppTx function does this for us - it creates an AppTx with the corresponding data, signs it, and sends it on to the blockchain.

RunTx

Ok, now we're ready to actually look at the implementation of the plugin in plugin.go. Note I'll leave out some of the methods as they don't serve any purpose for this example, but are necessary boilerplate. Your plugin may have additional requirements that utilize these other methods. Here's what's relevant for us:

type ExamplePluginState struct {
	Counter int
}

type ExamplePluginTx struct {
	Valid bool
}

type ExamplePlugin struct {
	name string
}

func (ep *ExamplePlugin) Name() string {
	return ep.name
}

func (ep *ExamplePlugin) StateKey() []byte {
	return []byte("ExamplePlugin.State")
}

func NewExamplePlugin() *ExamplePlugin {
	return &ExamplePlugin{
		name: "example-plugin",
	}
}

func (ep *ExamplePlugin) SetOption(store types.KVStore, key string, value string) (log string) {
	return ""
}

func (ep *ExamplePlugin) RunTx(store types.KVStore, ctx types.CallContext, txBytes []byte) (res abci.Result) {

	// Decode tx
	var tx ExamplePluginTx
	err := wire.ReadBinaryBytes(txBytes, &tx)
	if err != nil {
		return abci.ErrBaseEncodingError.AppendLog("Error decoding tx: " + err.Error())
	}

	// Validate tx
	if !tx.Valid {
		return abci.ErrInternalError.AppendLog("Valid must be true")
	}

	// Load PluginState
	var pluginState ExamplePluginState
	stateBytes := store.Get(ep.StateKey())
	if len(stateBytes) > 0 {
		err = wire.ReadBinaryBytes(stateBytes, &pluginState)
		if err != nil {
			return abci.ErrInternalError.AppendLog("Error decoding state: " + err.Error())
		}
	}

	//App Logic
	pluginState.Counter += 1

	// Save PluginState
	store.Set(ep.StateKey(), wire.BinaryBytes(pluginState))

	return abci.OK
}

All we're doing here is defining a state and transaction type for our plugin, and then using the RunTx method to define how the transaction updates the state. Let's break down RunTx in parts. First, we deserialize the transaction:

// Decode tx
var tx ExamplePluginTx
err := wire.ReadBinaryBytes(txBytes, &tx)
if err != nil {
	return abci.ErrBaseEncodingError.AppendLog("Error decoding tx: " + err.Error())
}

The transaction is expected to be serialized according to Tendermint's "wire" format, as defined in the github.com/tendermint/go-wire package. If it's not encoded properly, we return an error.

If the transaction deserializes correctly, we can now check if it's valid:

// Validate tx
if !tx.Valid {
	return abci.ErrInternalError.AppendLog("Valid must be true")
}

The transaction is valid if the Valid field is set, otherwise it's not - simple as that. Finally, we can update the state. In this example, the state simply counts how many valid transactions we've processed. But the state itself is serialized and kept in some store, which is typically a Merkle tree. So first we have to load the state from the store and deserialize it:

// Load PluginState
var pluginState ExamplePluginState
stateBytes := store.Get(ep.StateKey())
if len(stateBytes) > 0 {
	err = wire.ReadBinaryBytes(stateBytes, &pluginState)
	if err != nil {
		return abci.ErrInternalError.AppendLog("Error decoding state: " + err.Error())
	}
}

Note the state is stored under ep.StateKey(), which is defined above as ExamplePlugin.State. Also note, that we do nothing if there is no existing state data. Is that a bug? No, we just make use of Go's variable initialization, that pluginState will contain a Counter value of 0. If your app needs more initialization than empty variables, then do this logic here in an else block.

Finally, we can update the state's Counter, and save the state back to the store:

//App Logic
pluginState.Counter += 1

// Save PluginState
store.Set(ep.StateKey(), wire.BinaryBytes(pluginState))

return abci.OK

And that's it! Now that we have a simple plugin, let's see how to run it.

Running your plugin

In the previous tutorial, we used a pre-generated genesis.json and priv_validator.json for the application. This time, let's make our own.

First, let's create a new directory and change into it:

mkdir example-data
cd example-data

Now, let's create a new private key:

example-plugin key new > key.json

Here's what my `key.json looks like:

{
	"address": "15F591CA434CFCCBDEC1D206F3ED3EBA207BFE7D",
	"priv_key": [
		1,
		"737C629667A9EAADBB8E7CF792D5A8F63AA4BB51E06457DDD7FDCC6D7412AAAD43AA6C88034F9EB8D2717CA4BBFCBA745EFF19B13EFCD6F339EDBAAAFCD2F7B3"
	],
	"pub_key": [
		1,
		"43AA6C88034F9EB8D2717CA4BBFCBA745EFF19B13EFCD6F339EDBAAAFCD2F7B3"
	]
}

Now we can make a genesis.json file and add an account with out public key:

[
  "base/chainID", "example-chain",
  "base/account", {
    "pub_key": [1, "43AA6C88034F9EB8D2717CA4BBFCBA745EFF19B13EFCD6F339EDBAAAFCD2F7B3"],
    "coins": [
	{
	  "denom": "gold",
	  "amount": 1000000000,
	}
    ]
  }
]

Here we've granted ourselves 1000000000 units of the gold token.

Before we can start the blockchain, we must initialize and/or reset the Tendermint state for a new blockchain:

tendermint init
tendermint unsafe_reset_all

Great, now we're ready to go. To start the blockchain, simply run

example-plugin start --in-proc

In another window, we can try sending some transactions:

example-plugin tx send --to 0x1B1BE55F969F54064628A63B9559E7C21C925165 --amount 100gold --chain_id example-chain

Note the --chain_id flag. In the previous tutorial, we didn't include it because we were using the default chain ID ("test_chain_id"). Now that we're using a custom chain, we need to specify the chain explicitly on the command line.

Ok, so that's how we can send a SendTx transaction using our example-plugin CLI, but we were already able to do that with the basecoin CLI. With our new CLI, however, we can also send an ExamplePluginTx:

example-plugin tx example --amount 1gold --chain_id example-chain

The transaction is invalid! That's because we didn't specify the --valid flag:

example-plugin tx example --valid --amount 1gold --chain_id example-chain

Tada! We successfuly created, signed, broadcast, and processed our custom transaction type.

Query

Now that we've sent a transaction to update the state, let's query for the state. Recall that the state is stored under the key ExamplePlugin.State:

example-plugin query ExamplePlugin.State

Note the "value":"0101" piece. This is the serialized form of the state, which contains only an integer. If we send another transaction, and then query again, we'll see the value increment:

example-plugin tx example --valid --amount 1gold --chain_id example-chain
example-plugin query ExamplePlugin.State

Neat, right? Notice how the result of the query comes with a proof. This is a Merkle proof that the state is what we say it is. In a latter tutorial on Interblockchain Communication, we'll put this proof to work!

Next Steps

In this tutorial we demonstrated how to create a new plugin and how to extend the basecoin CLI to activate the plugin on the blockchain and to send transactions to it. Hopefully by now you have some ideas for your own plugin, and feel comfortable implementing them.

In the next tutorial, we tour through some other plugin examples, adding features for minting new coins, voting, and changin the Tendermint validator set. But first, you may want to learn a bit more about the design of the plugin system

12 KiB Raw Blame History