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



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;


The GoldRushDecoder class has different methods that enable the decoding logic to run. The various methods are

  1. initDecoder: Scans the ./services/decoder/protocols directory for all the protocols, extracts the configs from them and creates a mapping to the respective decoding function. It is run when the server starts.

  2. on: Creates a decoding function for the specified protocol name on the specified networks. Its declaration is:

    The method has 3 arguments:

  3. Event Id: A case-sensitive string concatenation of the protocol name with the event name by a :.

  4. Networks: An array of all the networks the defined decoding function will run for

  5. Decoding Function: The actual decoding function, it has 3 arguments passed to it:

    1. log: The raw log event that is being decoded.

    2. chain_name: Network to which the log belongs to.

    3. covalent_client: The covalent client created with your covalent API key.

  6. 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.

    ["<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.

  1. /tx/decode: Decodes a transaction of a network.

    Expects the JSON body:

    1. network: The chain name of the transaction

    2. tx_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.




 , 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 {
    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.