diff --git a/docs/guide/plugin-design.md b/docs/guide/plugin-design.md index 8f744ee01..17cb20010 100644 --- a/docs/guide/plugin-design.md +++ b/docs/guide/plugin-design.md @@ -64,6 +64,14 @@ and also to store arbitrary other information in the state. In this way, the functionality and state of a Basecoin-derived cryptocurrency can be greatly extended. One could imagine going so far as to implement the Ethereum Virtual Machine as a plugin! +Any required plugin initialization should be constructed within `SetOption`. +`SetOption` may be called during genesis of basecoin and can be used to set +initial plugin parameters. Within genesis.json file entries are made in +the format: "/", "" Where is the plugin name, +and and are the strings passed into the plugin SetOption function. +This function is intended to be used to set plugin specific information such +as the plugin state. + ## Examples To get started with plugins, see [the example-plugin tutorial](example-plugin.md). diff --git a/docs/guide/src/example-plugin/cmd.go b/docs/guide/src/example-plugin/cmd.go index 29e34e126..f9a3ff6af 100644 --- a/docs/guide/src/example-plugin/cmd.go +++ b/docs/guide/src/example-plugin/cmd.go @@ -41,12 +41,26 @@ func cmdExamplePluginTx(c *cli.Context) error { //Retrieve any flag results exampleFlag := c.Bool("valid") - //Create a transaction object with flag results + // Create a transaction object with flag results + // This object is responsible for passing on custom plugin information exampleTx := ExamplePluginTx{exampleFlag} - //Encode transaction bytes + // The custom plugin object is passed to the plugin in the form of + // a byte array. This is achieved serializing the object using go-wire. + // Once received in the plugin, these exampleTxBytes are decoded back + // into the original object struct ExamplePluginTx exampleTxBytes := wire.BinaryBytes(exampleTx) - //Send the transaction and return any errors + // Send the transaction and return any errors. + // Here exampleTxBytes will be passed on to the plugin through the + // following series of function calls: + // - commands.AppTx as data (cmd/commands/tx.go) + // - commands.broadcastTx as tx.Data (cmd/commands/tx.go) + // - after being broadcast the Tendermint transaction + // will be run through app.CheckTx, and if successful DeliverTx, + // let's assume app.CheckTx passes + // - app.DeliverTx serialized within txBytes as tx.Data (app/app.go) + // - state.ExecTx as tx.Data (state/execution.go) + // - plugin.RunTx as txBytes (docs/guide/src/example-plugin/plugin.go) return commands.AppTx(c, "example-plugin", exampleTxBytes) } diff --git a/docs/guide/src/example-plugin/plugin.go b/docs/guide/src/example-plugin/plugin.go index 12f5b6a66..97e80520a 100644 --- a/docs/guide/src/example-plugin/plugin.go +++ b/docs/guide/src/example-plugin/plugin.go @@ -13,10 +13,9 @@ import ( // Plugin State Struct // * Intended to store the current state of the plugin // * This example contains a field which holds the execution count -// * Used by go-wire as the encoding/decoding struct to hold the plugin state -// * All fields must be exposed (for go-wire) -// * The state is stored within the KVStore using the key retrieved -// from the ExamplePlugin.StateKey() function +// * Serialized (by go-wire) and stored within the KVStore using the key retrieved +// from the ExamplePlugin.StateKey() function/ +// * All fields must be exposed for serialization by external libs (here go-wire) type ExamplePluginState struct { Counter int } @@ -25,9 +24,8 @@ type ExamplePluginState struct { // * Stores transaction-specific plugin-customized information // * This example contains a dummy field 'Valid' intended to specify // if the transaction is a valid and should proceed -// * Used by go-wire as the encoding/decoding struct to pass transaction -// * All fields must be exposed (for go-wire) -// * Passed through txBytes in the RunTx func. +// * Deserialized (by go-wire) from txBytes in ExamplePlugin.RunTx +// * All fields must be exposed for serialization by external libs (here go-wire) type ExamplePluginTx struct { Valid bool } @@ -42,10 +40,7 @@ type ExamplePlugin struct { //----------------------------------------- // Non-Mandatory Functions -// Return a new example plugin pointer with a hard-coded name. Within other -// plugin implementations may choose to include other initialization -// information to populate custom fields of your Plugin struct in this example -// named ExamplePlugin +// Return a new ExamplePlugin pointer with a hard-coded name func NewExamplePlugin() *ExamplePlugin { return &ExamplePlugin{ name: "example-plugin", @@ -81,13 +76,12 @@ func (ep *ExamplePlugin) SetOption(store types.KVStore, key string, value string // Input fields: // - store types.KVStore // - This term provides read/write capabilities to the merkelized data store -// which is accessible cross-plugin +// which holds the basecoin state and is accessible to all plugins // - ctx types.CallContext // - The ctx contains the callers address, a pointer to the callers account, // and an amount of coins sent with the transaction // - txBytes []byte -// - Used to send customized information from the basecoin -// application to your plugin +// - Used to send customized information to your plugin // // Other more complex plugins may have a variant on the process order within this // example including loading and saving multiple or variable states, or not