​

What you’ll need

1. The contract address you’re interested in indexing.
2. The ABI (Application Binary Interface) of the contract.

​

Walkthrough

{
  "version": "1",
  "name": "friendtech",
  "abis": {
    "ftshares": {
      "path": "./abi.json"
    }
  },
  "instances": [
    {
      "abi": "ftshares",
      "address": "0xCF205808Ed36593aa40a44F10c7f7C2F67d4A4d4",
      "startBlock": 2430440,
      "chain": "base"
    }
  ]
}

​

Extending your subgraph with enrichments

Enrichments are a powerful way to add additional data to your subgraph by performing eth calls in the middle of an event or call handler.

See the enrichments configuration reference for more information on how to define these enrichments, and for an example configuration with enrichments.

​

Concepts

• Enrichments are defined at the instance level, and executed at the trigger handler level. This means that you can have different enrichments for different data sources or templates and that all enrichment executions are isolated to the handler they are being called from.
  • any additional imports from @graphprotocol/graph-ts beyond BigInt, Bytes, and store can be declared in the options.imports field of the enrichment (e.g., BigDecimal).
• Enrichments always begin by performing all eth calls first, if any eth calls are aborted then the enrichment as a whole is aborted.
  • calls marked as required or having another call declare them as a depends_on dependency will abort if the call is not successful, otherwise the call output value will remain as null.
  • calls marked as declared will configure the subgraph to execute the call prior to invoking the mapping handler. This can be useful for performance reasons, but only works for eth calls that have no mapping handler dependencies.
  • calls support pre and post expressions for conditions to test before and after the call, if either fails the call is aborted. Since these are expressions, they can be dynamic or constant values.
  • call source is an expression and therefore allows for dynamic values using math or concatenations. If the source is simply a contract address then it will be automatically converted to an Address type.
  • call params is an expression list and can also be dynamic values or constants.
• Enrichments support defining new entities as well as updating existing entities. If the entity name matches the trigger entity name, then the entity field mappings will be applied to the existing entity.
  • entity names should be singular and capitalized, this will ensure that the generated does not produce naming conflicts.
  • entity field mapping values are expressions and can be dynamic or constant values.
  • new enrichment entities are linked to the parent (trigger) entity that created them, with the parent (trigger) entity also linking to the new entity or entities in the opposite direction (always a collection type).
  • note that while you can define existing entities that are not the trigger entity, you may not update existing entities only create new instances of that entity.
  • entities support being created multiple times in a single enrichment, but require a unique id expression to be defined for each entity, id can by a dynamic value or a constant. this id is appended to the parent entity id to create a unique id for each enrichment entity in the list.
  • entities can be made mutable by setting the explicit_id flag to true, this will use the value of id without appending it to the parent entity id, creating an addressable entity that can be updated.

​

Snippets

Below are some various examples of configurations for different scenarios. To keep each example brief, we will only show the enrich section of the configuration, and in most cases only the part of the enrich section that is relevant. See the enrichments configuration reference for the full configuration reference.

​

Options

Here we are enabling debugging for the enrichment (this will output the enrichment steps to the subgraph log), as well as importing BigDecimal for use in a calls or entities section.

"enrich": {
  "options": {
    "imports": ["BigDecimal"],
    "debugging": true
  }
}

​

Call self

Here we are calling a function on the same contract as the trigger event. This means we can omit the abi and source configuration fields, as they are implied in this scenario, we only need to include the name and params fields (if the function declares paramters). We can refer to the result of this call using calls.balance.

"calls": {
  "balance": {
    "name": "balanceOf",
    "params": "event.params.owner"
  }
}

​

Call dependency

Here we are creating a 2-call dependency, where the second call depends on the first call (the params are calls.owner meaning we need the value of the owner call before we can invoke balanceOf). This means that if the first call fails, the second call will not be executed. Calls are always executed in the order they are configured, so the second call will have access to the output of the first call (in this example, we use that output as a parameter to the second call). We can list multiple calls in the depends_on array to create a dependency graph (if needed). Adding a call to the depends_on array will not automatically re-order the calls, so be sure to list them in the correct order.

"calls": {
  "owner": {
    "name": "ownerOf",
    "params": "event.params.id"
  },
  "balance": {
    "depends_on": ["owner"],
    "name": "balanceOf",
    "params": "calls.owner"
  }
}

​

External contract call for known address

Here we are calling a function on an external contract, where we know the address of the contract ahead of time. In this case, we need to include the abi and source configuration fields.

"calls": {
  "usdc_balance": {
    "abi": "erc20",
    "source": "0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48",
    "name": "balanceOf",
    "params": "event.params.owner"
  }
}

​

External contract call for dynamic address

Here we are setting up a 2 call chain to first determine the contract address, then call a function on that contract. In our example, the contractAddress function is returning an Address type so we can use the call result directly in the source field of the second call. If contractAddress was instead returning a string type, then we would use "source": "Address.fromString(calls.contract_address)", though this would be an unusual case to observe.

"calls": {
  "contract_address": {
    "name": "contractAddress",
    "params": "event.params.id"
  },
  "balance": {
    "depends_on": ["contract_address"],
    "abi": "erc20",
    "source": "calls.contract_address",
    "name": "balanceOf",
    "params": "event.params.owner"
  }
}

​

Required call

Here we are marking a call as required, meaning that if the call fails then the enrichment as a whole will be aborted. This is useful when you do not want to create a new entity (or enrich an existing entity) if the call does not return any meaningful data. Also note that when using depends_on, the dependency call is automatically marked as required. This should be used when the address of the contract being called may not always implement the function being called.

"calls": {
  "balance": {
    "abi": "erc20",
    "name": "balanceOf",
    "source": "event.params.address",
    "params": "event.params.owner",
    "required": true
  }
}

​

Pre and post conditions

Here we are using conditions to prevent a call from being executed or to abort the enrichment if the call result is not satisfactory. Avoiding an eth call can have a big performance impact if the inputs to the call are often invalid. Avoiding the creation of an entity can save on entity counts if the entity is not needed or useful for various call results. Conditions are simply checked at their target site in the enrichment, and evaluated to its negation to check if an abort is necessary (e.g., true becomes !(true), which is always false and therefore never aborts). In this example, we’re excluding the call if the owner is in a deny list, and we’re aborting the enrichment if the balance is 0.

"calls": {
  "balance": {
    "name": "balanceOf",
    "params": "event.params.owner",
    "conditions": {
      "pre": "![Address.zero().toHexString(), \"0x9C8fF314C9Bc7F6e59A9d9225Fb22946427eDC03\"].includes(event.params.owner.toHexString())",
      "post": "result.value.gt(BigInt.zero())"
    }
  }
}

​

Simple entity field mapping constant

Here were are simply replicating the id field from the event params into our enrichment entity. This can be useful if you want to filter or sort the enrichment entities by this field.

  "MyEntity": {
    "id uint256": "event.params.id"
  },

​

Simple entity field mapping expression

Here we are applying a serialization function to the value of a call result. This is necessary as the enrichment code generator does not resolve the effective type of an expression, so if there is a type mismatch a serialization function must be applied (in this case String vs Address).

  "MyEntity": {
    "owner address": "calls.owner.toHexString()"
  },

​

Complex entity field mapping expression

Here we are conditionally setting the value of usd_balance on whether or not the usdc_balance call was successful. If the call was not successful, then we set the value to BigDecimal.zero(), otherwise we divide the call result by 10^6 (USDC decimals) to convert the balance to a USD value.

  "MyEntity": {
    "usd_balance fixed": "calls.usdc_balance === null ? BigDecimal.zero() : calls.usdc_balance!.divDecimal(BigInt.fromU32(10).pow(6).toBigDecimal())"
  },

Can't find what you're looking for? Reach out to us at support@goldsky.com for help.

​

Multiple entity instances

Here we are creating multiple instances of an entity in a single enrichment. Each entity id will be suffixed with the provided id value.

  "MyEntity": [
    {
      "id": "'sender'",
      "mapping": {
        "balance fixed": "calls.balance"
      }
    },
    {
      "id": "'receiver'",
      "mapping": {
        "balance fixed": "calls.balance"
      }
    }
  ]

​

Addressable entity

Here we are creating an entity that is addressable by an explicit id. This means that we can update this entity with new values.

  "MyEntity": [
    {
      "id": "calls.owner.toHexString()",
      "explicit_id": true,
      "mapping": {
        "current_balance fixed": "calls.balance"
      }
    }
  ]

​

Examples

Here are some examples of various instant subgraph configurations. Each example builds on the previous example.

Each of these examples can be saved locally to a file (e.g., subgraph.json) and deployed using goldsky subgraph deploy nouns/1.0.0 --from-abi subgraph.json.

​

Simple NOUNS example

This is a basic instant subgraph configuration, a great starting point for learning about instant subgraphs.

{
  "version": "1",
  "name": "nouns/1.0.0",
  "abis": {
    "nouns": [
      {
        "anonymous": false,
        "inputs": [
          {
            "indexed": true,
            "internalType": "address",
            "name": "from",
            "type": "address"
          },
          {
            "indexed": true,
            "internalType": "address",
            "name": "to",
            "type": "address"
          },
          {
            "indexed": true,
            "internalType": "uint256",
            "name": "tokenId",
            "type": "uint256"
          }
        ],
        "name": "Transfer",
        "type": "event"
      }
    ]
  },
  "instances": [
    {
      "abi": "nouns",
      "address": "0x9C8fF314C9Bc7F6e59A9d9225Fb22946427eDC03",
      "startBlock": 12985438,
      "chain": "mainnet"
    }
  ]
}

​

NOUNS enrichment with receiver balance on transfer

This example describes a very simple enrichment that adds a balance field to a Balance enrichment entity. This balance field is populated by calling the balanceOf function on the to address of the Transfer event.

{
  "version": "1",
  "name": "nouns/1.0.0",
  "abis": {
    "nouns": [
      {
        "anonymous": false,
        "inputs": [
          {
            "indexed": true,
            "internalType": "address",
            "name": "from",
            "type": "address"
          },
          {
            "indexed": true,
            "internalType": "address",
            "name": "to",
            "type": "address"
          },
          {
            "indexed": true,
            "internalType": "uint256",
            "name": "tokenId",
            "type": "uint256"
          }
        ],
        "name": "Transfer",
        "type": "event"
      },
      {
        "inputs": [
          { "internalType": "address", "name": "owner", "type": "address" }
        ],
        "name": "balanceOf",
        "outputs": [
          { "internalType": "uint256", "name": "", "type": "uint256" }
        ],
        "stateMutability": "view",
        "type": "function"
      }
    ]
  },
  "instances": [
    {
      "abi": "nouns",
      "address": "0x9C8fF314C9Bc7F6e59A9d9225Fb22946427eDC03",
      "startBlock": 12985438,
      "chain": "mainnet",
      "enrich": {
        "handlers": {
          "Transfer(indexed address,indexed address,indexed uint256)": {
            "calls": {
              "balance": {
                "name": "balanceOf",
                "params": "event.params.to",
                "required": true
              }
            },
            "entities": {
              "Balance": {
                "owner address": "event.params.to.toHexString()",
                "balance uint256": "calls.balance"
              }
            }
          }
        }
      }
    }
  ]
}

​

NOUNS enrichment with sender & receiver balance on transfer entities

This example alters our previous example by capturing the balance field on both FromBalance and ToBalance enrichment entities. This balance field is populated by calling the balanceOf function on both the from and to address of the Transfer event.

{
  "version": "1",
  "name": "nouns/1.0.0",
  "abis": {
    "nouns": [
      {
        "anonymous": false,
        "inputs": [
          {
            "indexed": true,
            "internalType": "address",
            "name": "from",
            "type": "address"
          },
          {
            "indexed": true,
            "internalType": "address",
            "name": "to",
            "type": "address"
          },
          {
            "indexed": true,
            "internalType": "uint256",
            "name": "tokenId",
            "type": "uint256"
          }
        ],
        "name": "Transfer",
        "type": "event"
      },
      {
        "inputs": [
          { "internalType": "address", "name": "owner", "type": "address" }
        ],
        "name": "balanceOf",
        "outputs": [
          { "internalType": "uint256", "name": "", "type": "uint256" }
        ],
        "stateMutability": "view",
        "type": "function"
      }
    ]
  },
  "instances": [
    {
      "abi": "nouns",
      "address": "0x9C8fF314C9Bc7F6e59A9d9225Fb22946427eDC03",
      "startBlock": 12985438,
      "chain": "mainnet",
      "enrich": {
        "handlers": {
          "Transfer(indexed address,indexed address,indexed uint256)": {
            "calls": {
              "from_balance": {
                "name": "balanceOf",
                "params": "event.params.from",
                "required": true
              },
              "to_balance": {
                "name": "balanceOf",
                "params": "event.params.to",
                "required": true
              }
            },
            "entities": {
              "FromBalance": {
                "owner address": "event.params.from.toHexString()",
                "balance uint256": "calls.from_balance"
              },
              "ToBalance": {
                "owner address": "event.params.to.toHexString()",
                "balance uint256": "calls.to_balance"
              }
            }
          }
        }
      }
    }
  ]
}

​

NOUNS enrichment with mutable current balance on transfer for both sender & receiver

This example alters our previous example balance entities to become a single mutable Balance entity, so that both sender and receiver use the same entity.

{
  "version": "1",
  "name": "nouns/1.0.0",
  "abis": {
    "nouns": [
      {
        "anonymous": false,
        "inputs": [
          {
            "indexed": true,
            "internalType": "address",
            "name": "from",
            "type": "address"
          },
          {
            "indexed": true,
            "internalType": "address",
            "name": "to",
            "type": "address"
          },
          {
            "indexed": true,
            "internalType": "uint256",
            "name": "tokenId",
            "type": "uint256"
          }
        ],
        "name": "Transfer",
        "type": "event"
      },
      {
        "inputs": [
          { "internalType": "address", "name": "owner", "type": "address" }
        ],
        "name": "balanceOf",
        "outputs": [
          { "internalType": "uint256", "name": "", "type": "uint256" }
        ],
        "stateMutability": "view",
        "type": "function"
      }
    ]
  },
  "instances": [
    {
      "abi": "nouns",
      "address": "0x9C8fF314C9Bc7F6e59A9d9225Fb22946427eDC03",
      "startBlock": 12985438,
      "chain": "mainnet",
      "enrich": {
        "handlers": {
          "Transfer(indexed address,indexed address,indexed uint256)": {
            "calls": {
              "from_balance": {
                "name": "balanceOf",
                "params": "event.params.from",
                "required": true
              },
              "to_balance": {
                "name": "balanceOf",
                "params": "event.params.to",
                "required": true
              }
            },
            "entities": {
              "Balance": [
                {
                  "id": "event.params.from.toHexString()",
                  "explicit_id": true,
                  "mapping": {
                    "balance uint256": "calls.from_balance"
                  }
                },
                {
                  "id": "event.params.to.toHexString()",
                  "explicit_id": true,
                  "mapping": {
                    "balance uint256": "calls.to_balance"
                  }
                }
              ]
            }
          }
        }
      }
    }
  ]
}

{
  balance(id: "0x9C8fF314C9Bc7F6e59A9d9225Fb22946427eDC03") {
    id
    balance
  }
}

​

NOUNS enrichment with declared eth call

This example alters our previous example by adding the declared flag to boost performance of the balanceOf eth calls. declared calls only work for eth calls that have no mapping handler dependencies, in other words the call can be executed from the event params only. Also note that call handlers do not support delcared calls (yet), if declared is set on a call handler enrichment it will be ignored.

{
  "version": "1",
  "name": "nouns/1.0.0",
  "abis": {
    "nouns": [
      {
        "anonymous": false,
        "inputs": [
          {
            "indexed": true,
            "internalType": "address",
            "name": "from",
            "type": "address"
          },
          {
            "indexed": true,
            "internalType": "address",
            "name": "to",
            "type": "address"
          },
          {
            "indexed": true,
            "internalType": "uint256",
            "name": "tokenId",
            "type": "uint256"
          }
        ],
        "name": "Transfer",
        "type": "event"
      },
      {
        "inputs": [
          { "internalType": "address", "name": "owner", "type": "address" }
        ],
        "name": "balanceOf",
        "outputs": [
          { "internalType": "uint256", "name": "", "type": "uint256" }
        ],
        "stateMutability": "view",
        "type": "function"
      }
    ]
  },
  "instances": [
    {
      "abi": "nouns",
      "address": "0x9C8fF314C9Bc7F6e59A9d9225Fb22946427eDC03",
      "startBlock": 12985438,
      "chain": "mainnet",
      "enrich": {
        "handlers": {
          "Transfer(indexed address,indexed address,indexed uint256)": {
            "calls": {
              "from_balance": {
                "name": "balanceOf",
                "params": "event.params.from",
                "required": true,
                "declared": true
              },
              "to_balance": {
                "name": "balanceOf",
                "params": "event.params.to",
                "required": true,
                "declared": true
              }
            },
            "entities": {
              "Balance": [
                {
                  "id": "event.params.from.toHexString()",
                  "explicit_id": true,
                  "mapping": {
                    "balance uint256": "calls.from_balance"
                  }
                },
                {
                  "id": "event.params.to.toHexString()",
                  "explicit_id": true,
                  "mapping": {
                    "balance uint256": "calls.to_balance"
                  }
                }
              ]
            }
          }
        }
      }
    }
  ]
}