TCE plugins

Basic overview

When peers in a TCE session have loaded a plugin, each peer will host a local instance of that plugin. These instances of the plugin can interact with things like servers and crypto chains, and can communicate with each other through the TCE session by sending and reading plugin transactions, which TCE will attach to ConsensusEvents. Plugin transactions are not publicly visible to the application layer.

The application layer can interact with plugins by executing asynchronous functions in the plugin ("plugin commands"), and can receive feedback from plugins through the PluginEvents fields on finalized messages. If a plugin is implemented correctly, the plugin events attached to each finalized message by that plugin should be consistent between all creators in the session who have loaded that plugin.

Adding plugins to TCE

When initializing the TCE platform and configuring it as described here you will need to set these additional configuration options on the PlatformConfig.

• .EnablePlugin(bool) All plugin functionality is disabled by default, set this to true to enable it.

• .PluginPath(String) The path to the plugin directory. Defaults to the relative path "./plugins". TCE searches the plugin directory recursively for plugins.

• .AddPlugin(String) Pass the filename of a plugin in the plugin directory to add it to the session. Plugins take the form of dynamic libraries, for example "p_evm.dll". The exact filename will vary depending on the platform (for example, the same plugin might be called "libp_evm.so" on Linux).

Plugin bindings

A plugin's author should supply bindings that make it easy to use. Here's an example of what the bindings for a hypothetical plugin could look like.

// tcePlatform is created...

var coolPluginApi = new CoolPluginApi(tcePlatform);

// The bindings provided by the author will probably include some async
// functions like this.

var coolThingResult = await coolPluginApi.DoCoolThing(tcePlatform, arg1, arg2);

// The coolThingResult comes directly from your local instance of the plugin.
// Other creators in the session won't see this result, so it SHOULD NOT
// affect the synchronized application state.

if (tcePlatform.GetEvent() is Event tceEvent)
{
   // The bindings for a plugin should include a function 
   // for pulling any plugin events that originate from that plugin 
   // from each finalized TCE message.
   
   // If the plugin is implemented correctly, these ARE consistent 
   // between all creators in the session, so they can affect 
   // the synchronized application state.
   
   var coolPluginEvents = coolPluginApi.GetPluginEvents(tceEvent);
   
   HandleEvents(coolPluginEvents);
}

For technical details about how plugin bindings integrate with the TCE Platform, refer to the tce-plugin-common repo.