ipld-eth-server/plugins/README.md

## Plugins

This directory is for Exporter plugins (.go and .so files) generated by, output from, and linked to from the composeAndExecute command  
These plugins are generated using information provided in a .toml config file 

The config file requires, at a minimum, the below fields:

```toml 
[database]
    name = "vulcanize_public"
    hostname = "localhost"
    user = "vulcanize"
    password = "vulcanize"
    port = 5432

[client]
    ipcPath = "http://kovan0.vulcanize.io:8545"

[exporter]
    name = "exporter"
    [exporter.transformers]
            transformer1 = "github.com/path/to/transformer1"
            transformer2 = "github.com/path/to/transformer2"
            transformer3 = "github.com/path/to/transformer3"
            transformer4 = "github.com/different/path/to/transformer1"
    [exporter.repositories]
            transformers = "github.com/path/to"
            transformer4 = "github.com/different/path
    [exporter.migrations]
            transformers = "db/migrations"
            transformer4 = "to/db/migrations"
```

- `exporter.transformers` are mappings of import aliases to paths to `TransformerInitializer`s  
    -  Import aliases can be arbitrarily named but note that `interface1` is a reserved alias needed for the generic TransformerInitializer type  
- `exporter.repositores` are the paths to the repositories which contain the transformers   
- `exporter.migrations` are the relative paths to the db migrations found within the `exporter.repositores`  
    - Migrations need to be located in the repos in `exporter.repositores`  
    - Keys should match the keys for the corresponding repo  

If the individual transformers require additional configuration variables be sure to include them in the .toml file 

The general structure of a plugin .go file, and what we would see with the above config is shown below   

```go
package main

import (
	interface1 "github.com/vulcanize/vulcanizedb/libraries/shared/transformer"
	transformer1 "github.com/path/to/transformer1"
	transformer2 "github.com/path/to/transformer2"
	transformer3 "github.com/path/to/transformer3"
	transformer4 "github.com/different/path/to/transformer1"
)

type exporter string

var Exporter exporter

func (e exporter) Export() []interface1.TransformerInitializer {
	return []interface1.TransformerInitializer{
		transformer1.TransformerInitializer,
		transformer2.TransformerInitializer,
		transformer3.TransformerInitializer,
		transformer4.TransformerInitializer,
	}
}
```

As such, to plug in an external transformer we need to create a [package](https://github.com/vulcanize/maker-vulcanizedb/blob/compose_and_execute/pkg/autogen/test_helpers/bite/initializer.go) that exports a variable `TransformerInitializer` that is of type [TransformerInitializer](https://github.com/vulcanize/maker-vulcanizedb/blob/compose_and_execute/libraries/shared/transformer/transformer.go#L19)   
As long as the imported transformers abide by the required interfaces, we can execute over any arbitrary set of them   
Note: currently the transformers must also operate using this watcher's [execution mode](https://github.com/vulcanize/maker-vulcanizedb/blob/compose_and_execute/libraries/shared/watcher/watcher.go#L80), in the future the watcher will become pluggable as well  

For each transformer we will also need to create db migrations to run against vulcanizeDB so that we can store the transformed data  
The migrations needed for a specific transformer need to be included in the same repository as the transformer(s) that require them, and their relative paths in that repo must be specified in the config as discussed above

NOTE: Due to a bug with plugin migrations, currently need to leave the `exporter.migrations` blank and manually run migrations before running composeAndExecute