improve README

injective-common/README.md

@@ -2,23 +2,79 @@
 
 The Injective Foundational modules are Substreams modules extracting common data from the Injective blockchain.
 
+## Getting the substreams package
+
+### From Substreams.dev
+
+https://substreams.dev/streamingfast/injective-common/
+
+
+### Building it yourself
+
+### Protobuf definitions bundle
+
+The required protobuf modules are referenced in `buf.yaml` and bundled in `generated-buf-build.binpb`
+
+If you want to add more, you will need a (free) API token to access https://buf.build
+The `make` command will automatically run the appropriate `buf build` command if needed.
+
+### Generate rust protobuf bindings
+
+```bash
+make protogen
+```
+
+### Build Substreams modules
+
+```bash
+make build
+```
+
+### Run Substreams
+
+You will need an API key to access the streamingfast servers, see https://substreams.streamingfast.io
+
+```bash
+substreams run -e mainnet.injective.streamingfast.io:443 substreams.yaml filtered_events -p filtered_events='type:injective.peggy.v1.EventDepositClaim' -s 9600 -t 9700
+substreams run -e testnet.injective.streamingfast.io:443 substreams.yaml filtered_events -p filtered_events='type:injective.exchange.v1beta1.EventCancelSpotOrder' -s 27751658 -t +10
+```
+
+### Package it as .spkg
+
+* optionally bump the version number in substreams.yaml
+
+```bash
+make package
+```
+
 ## Modules
 
 ### all_events
 
-The `all_events` module extracts only the events and provides them, along with the transaction hash and block at which it they are found.
+The `all_events` module reads from the `sf.cosmos.type.v2.Block` source and outputs a list of all events in the block,
+Some events are at the block level, others appear inside the transactions. The latter will include the transaction hash.
 
 ### filtered_events
 
-The `filtered_events` module allows a reduction of the `all_events` output, only matching the events that match the requested type.
+The `filtered_events` module allows a reduction of the `all_events` output, only matching the events that match the 
+requested type or include the attribute keys.
+It pre-filters blocks using the `index_events` module for efficiency.
 
-Use with the parameter, ex:
+Use with parameters, ex:
 
 ```bash
-substreams run [...] -p filtered_events="message || injective.peggy.v1.EventDepositClaim"
+substreams run [...] -p filtered_events="(type:message && attr:action) || (type:wasm && attr:_contract_address)"
 ```
 
-### all_transactions (work in progress)
+### filtered_event_groups
+
+The `filtered_event_groups` module reads from `all_events` and applies a filter on the event types and attribute keys, 
+outputting *all the events* from transactions that have at least one event matching the filter.
+It pre-filters blocks using the `index_events` module for efficiency.
+
+Use with the same parameters as the `filtered_events` module.
+
+### all_transactions
 
 The `all_transactions` module extracts all the transactions from the Injective blockchain, providing useful information, such as _messages_, _signatures_ or _events_.
 
@@ -27,46 +83,47 @@ The other types will still be shown as protobuf "Any" type.
 
 ### filtered_trx_by_events
 
-The `filtered_trx_by_events` modules allows a reduction of the `all_transactions` output, only matching the events that match the requested type. The module will return the entire transactions. Some event types will appear that do not match from the filtered params as the entire transaction is returned.
 
-Use with the parameter, ex:
+The `filtered_trx_by_events` modules reads from `all_transactions` and applies a filter on the event types and attribute keys, 
+outputting the complete transactions that have at least one event matching the filter.
+It pre-filters blocks using the `index_events` module for efficiency.
 
-```bash
-substreams run [...] -p filtered_trx_by_events="message || injective.peggy.v1.EventDepositClaim"
-```
+Use with the same parameters as the `filtered_events` module.
 
-## Getting Started
 
-### Gather protobuf definitions in generated-buf-build.binpb
+### filtered_events_by_attribute_value
 
-The required protobuf modules are referenced in `buf.yaml`.
-You need a (free) API token to access https://buf.build and resolve the dependencies into a single file, generated-buf-build.binpb.
-That file is then used to generate the rust protobuf bindings or to bundle the definitions in the .spkg. (it is referenced in the substreams.yaml)
+The `filtered_events_by_attribute_value` module reads from `all_events` and applies a filter on the event types, 
+attribute keys and values, only outputting the events that match the filter. 
 
-### Generate rust protobuf bindings
+Use with parameters, ex:
 
 ```bash
-make protogen
+substreams run [...] -p filtered_events_by_attribute_value="type:wasm && attr:_contract_address:inj1v77y5ttah96dc9qkcpc88ad7rce8n88e99t3m5"
 ```
 
-### Build Substreams modules
+For an optimized experience, we recommend importing this module in your own substreams.yaml, overloading 
+the 'blockFilter' with a custom query to `index_events`, with the `use` parameter. See [an example](./derived-substreams-example.yaml)
 
-```bash
-make build
-```
 
-### Run Substreams
+### filtered_event_groups_by_attribute_value
 
-You will need an API key to access the streamingfast servers, see https://substreams.streamingfast.io
+The `filtered_events_groups_by_attribute_value` module reads from `all_events` and applies a filter on the event types,
+attribute keys and values, outputting all the events from transactions that have at least one event matching the filter.
 
-This example query only fetches the events of type 'injective.peggy.v1.EventDepositClaim'
+Use with the same parameters as the `filtered_events_by_attribute_value` module.
 
-```bash
-substreams run -e mainnet.injective.streamingfast.io:443 substreams.yaml filtered_events -p filtered_events='injective.peggy.v1.EventDepositClaim' -s 9600 -t 9700
-```
+For an optimized experience, we recommend importing this module in your own substreams.yaml, overloading 
+the 'blockFilter' with a custom query to `index_events`, with the `use` parameter. See [an example](./derived-substreams-example.yaml)
 
-### Package as .spkg
 
-```bash
-make package
-```
+### filtered_trx_by_events_attribute_value
+
+The `filtered_trx_by_events_attribute_value` module reads from `all_events` and applies a filter on the event types, 
+attribute keys and values, outputting the complete transactions that have at least one event matching the filter.
+
+Use with the same parameters as the `filtered_events_by_attribute_value` module.
+
+For an optimized experience, we recommend importing this module in your own substreams.yaml, overloading 
+the 'blockFilter' with a custom query to `index_events`, with the `use` parameter. See [an example](./derived-substreams-example.yaml)
+