GoldRush Decoder Quickstart
This repository contains the logic for decoding a raw log event
of a transaction to meaningful, human-readable, structured data. Check out the repository here.
Knowledge Primer
Config
A `config` is a mapping of a contract address, network, and protocol name to create a unique configuration for every protocol on all the networks across all the chains for all the contracts. A protocol can have a collection of configs in an array.
export type Configs = { protocol_name: string; network: Chain; address: string; is_factory: boolean; }[];
GoldRushDecoder
The GoldRushDecoder
class has different methods that enable the decoding logic to run. The various methods are
initDecoder
: Scans the./services/decoder/protocols
directory for all the protocols, extracts theconfigs
from them and creates a mapping to the respective decoding function. It is run when the server starts.on
: Creates a decoding function for the specified protocol name on the specified networks. Its declaration is:The method has 3 arguments:
Event Id: A case-sensitive string concatenation of the
protocol name
with theevent name
by a:
.Networks: An array of all the networks the defined decoding function will run for
Decoding Function: The actual decoding function, it has 3 arguments passed to it:
log
: The raw log event that is being decoded.chain_name
: Network to which the log belongs to.covalent_client
: The covalent client created with your covalent API key.
decode
: The function that chooses which decoding function needs to be called for which log event. It collects all the decoded events for a transaction and returns them in an array of structured data. It is run when the API server receives a request.
GoldRushDecoder.on( "<protocol-name>:<EventName>", ["<network_1>", "<network_2>"], ABI as Abi, async (log, chain_name, covalent_client): Promise<EventType> => { <!-- decoding logic --> } );
Running the Development Server
Follow the following steps to start the development server of the GoldRush Decoder.
Install the dependencies.
yarn install
Setup the environmental variables. Refer to .env.example for the list of environmental variables and store them in .env
at the root level of the repository.
Start the server.
yarn dev
API Endpoints
/api/v1
: The default endpoint for the v1 of the server. A header of the key x-covalent-api-key
with the value as the Covalent API key is mandatory for the Decoder to work.
/tx/decode
: Decodes a transaction of a network.Expects the JSON body:
network
: The chain name of the transactiontx_hash
: Hash of the transaction to be decoded.
curl --location 'http://localhost:<PORT>/api/v1/tx/decode' \ --header 'x-covalent-api-key: <COVALENT_API_KEY>' \ --header 'Content-Type: application/json' \ --data '{ "network": "<CHAIN_NAME>", "tx_hash": "<TX_HASH>" }'
Adding a Decoder
Run this on your terminal.
yarn add-config
Add a Protocol Name for which you want to add an config. If the protocol does not exist, a new protocol will be created. However, if it does exist, another config will be added for that protocol.
Input data as per the prompts. The data required after the protocol_name
is
address
: This is the contract address. It can either be a standalone contract or a factory contract.is_factory
: If the input address is a factory contract or not.network
: The network or chain the added config is for.
This will modify the configs added to the Protocols folder. A config will be added to ${protocol_name}.configs.ts
. A sample decoder with a dummy event name (<EVENT NAME>
) will be added to ${protocol_name}.decoder.ts
. Along with this, a test file ${protocol_name}.test.ts
will also be created which needs to be fixed so that the test passes.
In
${protocol_name}.decoder.ts
, a decoding logic declaration (
Decoder.on(...) {...}
) will be exposed wherein the decoding logic needs to be implemented. The return type of the decoding function expects:
export interface EventType { category: DECODED_EVENT_CATEGORY; action: DECODED_ACTION; name: string; protocol?: { name: string; logo: string; }; tokens?: { heading: string; value: string; decimals: number; ticker_symbol: string | null; ticker_logo: string | null; pretty: string; }[]; nfts?: { heading: string; collection_name: string | null; token_identifier: string | null; collection_address: string; images: { default: string | null; 256: string | null; 512: string | null; 1024: string | null; }; }[]; details?: { title: string; value: string; }[]; }
Next Steps for Contribution
Checkout a Branch
Before making any changes to the codebase, it's essential to create a new branch to isolate your changes. Follow these steps to checkout a branch.
Add a Configuration Using the CLI
The decoder allows users to configure various aspects of its functionality via a command-line interface (CLI).
Satisfy the Tests
Ensuring that your changes pass all tests is crucial to maintaining the quality and stability of the project. Follow these steps to satisfy the tests.
Open a Pull Request (PR)
Once you've implemented your changes and ensured they pass all tests, it's time to open a pull request (PR) to propose merging your changes into the main project repository.