Merge pull request #42 from nautls/start-documentation

Start documentation

Author: arobsn

README.md

@@ -1 +1,49 @@
 # Ergomatic
+
+[![ci](https://github.com/nautls/ergomatic/actions/workflows/ci.yaml/badge.svg)](https://github.com/nautls/ergomatic/actions/workflows/ci.yaml)
+[![Discord badge][]][Discord link]
+
+`ergomatic` is a generic off-chain execution framework for bots. Bot
+functionality is provided via plugins which are audited by the nautilus team.
+
+## Install
+
+Shell (Mac, Linux):
+
+```sh
+curl -fsSL https://raw.githubusercontent.com/nautls/ergomatic/main/scripts/install/install.sh | sh
+```
+
+PowerShell (Windows):
+
+```powershell
+irm https://raw.githubusercontent.com/nautls/ergomatic/main/scripts/install/install.ps1 | iex
+```
+
+### Running
+
+Ergomatic can be ran using the `run` CLI command. The `-c` flag can optionally
+be passed to specify the config file path, if not provided it will default to
+`$CWD/ergomatic.yaml`.
+
+```sh
+ergomatic run
+```
+
+Logs can be viewed in your terminal and are also persisted to disk depending on
+OS:
+
+- Linux: `$XDG_DATA_HOME/ergomatic`
+- macOS: `$HOME/Library/Application Support/ergomatic`
+- Windows: `$LOCALAPPDATA/ergomatic`
+
+Log files will automatically be rotated with a maximum of 300mb of logs kept.
+
+## Contributing
+
+We appreciate your help!
+
+To contribute, please read our [contributing instructions](CONTRIBUTING.md).
+
+[Discord badge]: https://img.shields.io/discord/668903786361651200?logo=discord&style=social
+[Discord link]: https://discord.gg/ergo-platform-668903786361651200

docs/plugins.md

@@ -0,0 +1,58 @@
+# Plugins
+
+## Creating a Plugin
+
+For this exercise lets assume I am creating a plugin for my dapp that requires
+off-chain bot functionality, my dapp is called "Degenz".
+
+Firstly decide on a `id` for your plugin, this should be in `snake_case` format,
+in my case I will use `degenz`.
+
+The easiest way to get started is to use the provided plugin template:
+
+```
+cp -r plugins/_template plugins/degenz
+```
+
+Next update the naming of various variables and classes to match your dapp, for
+example:
+
+```
+export const _TEMPLATE_PLUGIN_ID = "_template_plugin"; -> export const DEGENZ_PLUGIN_ID = "degenz";
+interface _TemplatePluginConfig -> interface DegenzPluginConfig
+class TemplatePlugin -> class DegenzPlugin
+```
+
+The template contains placeholder implementations for each plugin method, update
+these to implement your plugins logic as required. `onStart` is where you should
+do any initialization logic such as starting of tasks, etc. `onStop` is where
+any clean-up logic should be placed, destroying of tasks, persisting of any
+data, etc.
+
+Finally register your plugin for usage by added it to `pluginConstructorMap` in
+`plugins/mod.ts` like so:
+
+```ts
+import { PluginConstructor } from "../src/plugins/plugin.ts";
+import { EXAMPLE_PLUGIN_ID, ExamplePlugin } from "./example_plugin/mod.ts";
+import { DEGENZ_PLUGIN_ID, DegenzPlugin } from "./degenz/mod.ts";
+
+export const pluginConstructorMap: Record<string, PluginConstructor> = {
+  [EXAMPLE_PLUGIN_ID]: ExamplePlugin,
+  [DEGENZ_PLUGIN_ID]: DegenzPlugin,
+};
+```
+
+Now you should be all set to add your plugin to your `ergomatic` configuration
+file. For example:
+
+```toml
+logLevel: INFO
+plugins:
+    - id: degenz
+      enabled: true
+      logLevel: DEBUG
+      config:
+        configValue: "testing"
+        otherConfigValue: 5
+```

plugins/_template/mod.ts

@@ -0,0 +1,83 @@
+import { Block, SignedTransaction } from "@fleet-sdk/common";
+import { BlockchainSnapshot } from "../../src/blockchain/blockchain_monitor.ts";
+import { Plugin, PluginDescriptor } from "../../src/plugins/mod.ts";
+import { z } from "zod/mod.ts";
+
+export const _TEMPLATE_PLUGIN_ID = "_template_plugin";
+
+interface _TemplatePluginConfig {
+  configValue: string;
+  otherConfigValue: number;
+}
+
+export class _TemplatePlugin extends Plugin<_TemplatePluginConfig> {
+  get descriptor(): PluginDescriptor {
+    return {
+      // Human readable name of your plugin
+      name: "Template Plugin",
+      // Description of your plugins functionality and anything else users should be aware of
+      description:
+        "Template for developers to get started creating their own plugins",
+      // Version of your plugin
+      version: "0.1.0",
+    };
+  }
+
+  onStart(): Promise<void> {
+    this.logger.info(`started with configuration: ${this.config}`);
+
+    return Promise.resolve();
+  }
+
+  onStop(): Promise<void> {
+    this.logger.info("Plugin shutting down, performing cleanup!");
+
+    return Promise.resolve();
+  }
+
+  onNewBlock(
+    block: Block,
+    snapshot: Readonly<BlockchainSnapshot>,
+  ): Promise<void> {
+    this.logger.info(`block: ${block}, snapshot: ${snapshot}`);
+
+    return Promise.resolve();
+  }
+
+  onMempoolTx(
+    tx: SignedTransaction,
+    snapshot: Readonly<BlockchainSnapshot>,
+  ): Promise<void> {
+    this.logger.info(`mempool tx: ${tx}, snapshot: ${snapshot}`);
+
+    return Promise.resolve();
+  }
+
+  onIncludedTx(
+    tx: SignedTransaction,
+    snapshot: Readonly<BlockchainSnapshot>,
+  ): Promise<void> {
+    this.logger.info(`tx included in block: ${tx}, snapshot: ${snapshot}`);
+
+    return Promise.resolve();
+  }
+
+  onMempoolTxDrop(
+    tx: SignedTransaction,
+    snapshot: Readonly<BlockchainSnapshot>,
+  ): Promise<void> {
+    this.logger.warning(
+      `tx dropped from mempool without being included in block: ${tx}, snapshot: ${snapshot}`,
+    );
+
+    return Promise.resolve();
+  }
+
+  // deno-lint-ignore no-explicit-any
+  configSchema(): z.ZodObject<any> | undefined {
+    return z.object({
+      configValue: z.string(),
+      otherConfigValue: z.number(),
+    });
+  }
+}