Merge pull request #142 from taikoxyz/TP-405--improve-readme

TP-405--improve-readme

README.md

@@ -1,14 +1,14 @@
-# Trailblazer Whitelisted Protocols
+# Trailblazer Whitelisted Protocols and Adapters
 
-## Adding a New Protocol to the Whitelist
+## Adding a new Protocol to the Whitelist
 
 ### 1. Modify `protocols.json`
 
 Open [`protocols.json`](./whitelist/protocols.json) and add a new protocol entry to the whitelist.
 
 ### 2. Example Protocol Entry
 
-A new protocol entry needs atleast a name, slug and its contract addresses. Optionally, add twitter and logo reference. Logo must be stored under `/img`. Ensure your slug is consistent with your project's slug used in Defillama if you are integrated.
+A new protocol entry needs atleast a name, slug and its contract addresses. Optionally, add twitter and logo reference. Logo must be stored under `./img`. Ensure your slug is consistent with your project's slug used in Defillama if you are integrated.
 
 ```json
 {
@@ -17,7 +17,9 @@ A new protocol entry needs atleast a name, slug and its contract addresses. Opti
     "contracts": [
         "0x0"
         ...
-    ]
+    ],
+    "twitter": "@optional-protocol-twitter",
+    "logo": "optional-protocol-logo.jpg",
 }
 ```
 
@@ -28,3 +30,26 @@ Create a pull request (PR) on GitHub to merge your changes into the main branch.
 ### 4. Review and Merge
 
 Wait for the PR to be reviewed by the maintainers. Once approved, your changes will be merged, and the new protocol will be added to the whitelist.
+
+
+## Adding a new Adapter
+
+### 1. Add your Project under `adapters/projects`
+
+After the details of the indexer has been confirmed with the team, add your project's indexer in the `adapters/projects` folder. See `adapters/adapters.go` for interfaces and types.
+
+### 2. Write your Indexer
+
+An example adapter for tracking OrderFulfilled Event on the OKX marketplace can be seen [here](./projects/okx/order_fulfilled.go) along with its accompanying test file.
+
+### 3. Manually Test your Adapter by adding it to the CLI
+
+First, add a new adapter in `cmd/adapter.go`. Second, add adapter to switch case of `cmd/cmd.go`'s function `executeCommand`. Test out the CLI with `go run .` from project root.
+
+### 4. Create a Pull Request
+
+Create a pull request (PR) on GitHub to merge your changes into the main branch. Provide a clear description of the changes and the protocol added.
+
+### 5. Review and Merge
+
+Wait for the PR to be reviewed by the maintainers. Once approved, your changes will be merged, and the protocol info will be added to trailblazers.

adapters/adapters.go

@@ -22,13 +22,16 @@ func ZeroAddress() common.Address {
 	return common.HexToAddress("0x0000000000000000000000000000000000000000")
 }
 
+// Whitelist contains information for general whitelisted protocols
 type Whitelist struct {
 	User        common.Address
 	Time        uint64
 	BlockNumber uint64
 	TxHash      common.Hash
 }
 
+// LPTransfer is used for LP transfers.
+// For examples, see Izumi and Ritsu.
 type LPTransfer struct {
 	From           common.Address
 	To             common.Address
@@ -43,6 +46,8 @@ type LPTransfer struct {
 	TxHash         common.Hash
 }
 
+// Lock is used for token locking campaign.
+// For examples, see Drips and Symmetric.
 type Lock struct {
 	User          common.Address
 	TokenAmount   *big.Int
@@ -54,11 +59,8 @@ type Lock struct {
 	TxHash        common.Hash
 }
 
-type LogIndexer[T any] interface {
-	Addresses() []common.Address
-	Index(context.Context, ...types.Log) ([]T, error)
-}
-
+// Prdiction is used for prediction campaign.
+// For examples, see Robinos.
 type Prediction struct {
 	User          common.Address
 	TokenAmount   *big.Int
@@ -70,6 +72,17 @@ type Prediction struct {
 	TxHash        common.Hash
 }
 
+// LogIndexer is the generic interface for indexing logs into types above.
+// By indexing, it parses information of logs.
+type LogIndexer[T any] interface {
+	// Addresses returns indexed contract addresses.
+	Addresses() []common.Address
+	// Index transforms given logs into types above.
+	Index(context.Context, ...types.Log) ([]T, error)
+}
+
+// BlockProcessor is the generic interface for indexing block information.
+// By block processing, it parses information of blocks.
 type BlockProcessor[T any] interface {
 	Process(context.Context, ...*types.Block) ([]T, error)
 }