envio/fuel.schema.json

A latency and sync speed optimized, developer friendly blockchain data indexer.

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "title": "Envio Config Schema",
  "description": "Schema for a YAML config for an envio indexer",
  "type": "object",
  "properties": {
    "name": {
      "description": "Name of the project",
      "type": "string"
    },
    "description": {
      "description": "Description of the project",
      "type": [
        "string",
        "null"
      ]
    },
    "schema": {
      "description": "Custom path to schema.graphql file",
      "type": [
        "string",
        "null"
      ]
    },
    "handlers": {
      "description": "Optional relative path to handlers directory for auto-loading. Defaults to 'src/handlers' if not specified.",
      "type": [
        "string",
        "null"
      ]
    },
    "full_batch_size": {
      "description": "Target number of events to be processed per batch. Set it to smaller number if you have many Effect API calls which are slow to resolve and can't be batched. (Default: 5000)",
      "type": [
        "integer",
        "null"
      ],
      "format": "uint64",
      "minimum": 0
    },
    "storage": {
      "description": "Storage backends the indexer writes data to. Defaults to Postgres when omitted. Set `clickhouse: true` to additionally sync the indexed data to ClickHouse. Mark a backend with `default: true` to store entities that don't have an @storage directive in the schema, e.g. `clickhouse: {default: true}`.",
      "anyOf": [
        {
          "$ref": "#/$defs/StorageConfig"
        },
        {
          "type": "null"
        }
      ]
    },
    "ecosystem": {
      "description": "Ecosystem of the project.",
      "$ref": "#/$defs/EcosystemTag"
    },
    "contracts": {
      "description": "Global contract definitions that must contain all definitions except addresses. You can share a single handler/abi/event definitions for contracts across multiple chains.",
      "type": [
        "array",
        "null"
      ],
      "items": {
        "$ref": "#/$defs/GlobalContract"
      }
    },
    "chains": {
      "description": "Configuration of the blockchain chains that the project is deployed on.",
      "type": "array",
      "items": {
        "$ref": "#/$defs/Chain"
      }
    },
    "raw_events": {
      "description": "If true, the indexer will store the raw event data in the database. This is useful for debugging, but will increase the size of the database and the amount of time it takes to process events (default: false)",
      "type": [
        "boolean",
        "null"
      ]
    }
  },
  "additionalProperties": false,
  "required": [
    "name",
    "ecosystem",
    "chains"
  ],
  "$defs": {
    "StorageConfig": {
      "type": "object",
      "properties": {
        "postgres": {
          "description": "Whether to use Postgres as a storage backend (default: true). Accepts a boolean or an options object (the object form implies the backend is enabled).",
          "anyOf": [
            {
              "type": [
                "boolean",
                "null"
              ]
            },
            {
              "type": "object",
              "properties": {
                "default": {
                  "description": "Whether entities without an @storage directive are stored in this backend (default: true when Postgres is the only enabled backend, false otherwise).",
                  "type": [
                    "boolean",
                    "null"
                  ]
                },
                "column_name_format": {
                  "description": "How entity fields are reflected in the storage column names. `original` keeps the schema.graphql field names as is, `snake_case` converts them to snake_case in the database while keeping the original casing in the exposed APIs. (default: original)",
                  "type": [
                    "string",
                    "null"
                  ],
                  "enum": [
                    "original",
                    "snake_case",
                    null
                  ]
                }
              },
              "additionalProperties": false
            }
          ]
        },
        "clickhouse": {
          "description": "Whether to additionally sync the indexed data to ClickHouse. Requires Postgres to be enabled (default: false). Accepts a boolean or an options object (the object form implies the backend is enabled).",
          "anyOf": [
            {
              "type": [
                "boolean",
                "null"
              ]
            },
            {
              "type": "object",
              "properties": {
                "default": {
                  "description": "Whether entities without an @storage directive are stored in this backend (default: false).",
                  "type": [
                    "boolean",
                    "null"
                  ]
                },
                "column_name_format": {
                  "description": "How entity fields are reflected in the storage column names. `original` keeps the schema.graphql field names as is, `snake_case` converts them to snake_case in the database while keeping the original casing in the exposed APIs. (default: original)",
                  "type": [
                    "string",
                    "null"
                  ],
                  "enum": [
                    "original",
                    "snake_case",
                    null
                  ]
                }
              },
              "additionalProperties": false
            }
          ]
        }
      },
      "additionalProperties": false,
      "allOf": [
        {
          "not": {
            "properties": {
              "postgres": {
                "const": false
              }
            },
            "required": [
              "postgres"
            ]
          }
        },
        {
          "if": {
            "properties": {
              "clickhouse": {
                "anyOf": [
                  {
                    "const": true
                  },
                  {
                    "type": "object"
                  }
                ]
              }
            },
            "required": [
              "clickhouse"
            ]
          },
          "then": {
            "properties": {
              "postgres": {
                "anyOf": [
                  {
                    "const": true
                  },
                  {
                    "type": "object"
                  }
                ]
              }
            },
            "required": [
              "postgres"
            ]
          }
        }
      ]
    },
    "EcosystemTag": {
      "type": "string",
      "enum": [
        "fuel"
      ]
    },
    "GlobalContract": {
      "type": "object",
      "properties": {
        "name": {
          "description": "A unique project-wide name for this contract (no spaces)",
          "type": "string"
        },
        "abi_file_path": {
          "description": "Relative path (from config) to a json abi.",
          "type": "string"
        },
        "handler": {
          "description": "Optional relative path to a file where handlers are registered for the given contract. If not provided, handlers can be auto-loaded from src directory.",
          "type": [
            "string",
            "null"
          ]
        },
        "events": {
          "description": "A list of events that should be indexed on this contract",
          "type": "array",
          "items": {
            "$ref": "#/$defs/EventConfig"
          }
        }
      },
      "additionalProperties": false,
      "required": [
        "name",
        "abi_file_path",
        "events"
      ]
    },
    "EventConfig": {
      "type": "object",
      "properties": {
        "name": {
          "description": "Name of the event in the HyperIndex generated code",
          "type": "string"
        },
        "type": {
          "description": "Explicitly set the event type you want to index. It's derived from the event name and fallbacks to LogData.",
          "anyOf": [
            {
              "$ref": "#/$defs/EventType"
            },
            {
              "type": "null"
            }
          ]
        },
        "logId": {
          "description": "An identifier of a logged type from ABI. Used for indexing LogData receipts. The option can be omitted when the event name matches the logged struct/enum name.",
          "type": [
            "string",
            "null"
          ]
        }
      },
      "additionalProperties": false,
      "required": [
        "name"
      ]
    },
    "EventType": {
      "type": "string",
      "enum": [
        "logData",
        "mint",
        "burn",
        "transfer",
        "call"
      ]
    },
    "Chain": {
      "type": "object",
      "properties": {
        "id": {
          "description": "Public chain id",
          "type": "integer",
          "format": "uint64",
          "minimum": 0
        },
        "skip": {
          "description": "Excludes the chain from indexing and migrations. Code generation is unaffected. For testing, prefer using a test framework instead.",
          "type": [
            "boolean",
            "null"
          ]
        },
        "start_block": {
          "description": "The block at which the indexer should start ingesting data",
          "type": "integer",
          "format": "uint64",
          "minimum": 0
        },
        "end_block": {
          "description": "The block at which the indexer should terminate.",
          "type": [
            "integer",
            "null"
          ],
          "format": "uint64",
          "minimum": 0
        },
        "hyperfuel_config": {
          "description": "Optional HyperFuel Config for additional fine-tuning",
          "anyOf": [
            {
              "$ref": "#/$defs/HyperfuelConfig"
            },
            {
              "type": "null"
            }
          ]
        },
        "max_reorg_depth": {
          "description": "The number of blocks from the head that the indexer should account for in case of reorgs.",
          "type": [
            "integer",
            "null"
          ],
          "format": "uint32",
          "minimum": 0
        },
        "block_lag": {
          "description": "The number of blocks behind the chain head that the indexer should lag. Useful for avoiding reorg issues by indexing slightly behind the tip.",
          "type": [
            "integer",
            "null"
          ],
          "format": "uint32",
          "minimum": 0
        },
        "contracts": {
          "description": "All the contracts that should be indexed on the given chain",
          "type": [
            "array",
            "null"
          ],
          "items": {
            "$ref": "#/$defs/ChainContract"
          }
        }
      },
      "additionalProperties": false,
      "required": [
        "id",
        "start_block"
      ]
    },
    "HyperfuelConfig": {
      "type": "object",
      "properties": {
        "url": {
          "description": "URL of the HyperFuel endpoint (default: The most stable HyperFuel endpoint for the network)",
          "type": "string"
        }
      },
      "additionalProperties": false,
      "required": [
        "url"
      ]
    },
    "ChainContract": {
      "type": "object",
      "properties": {
        "name": {
          "description": "A unique project-wide name for this contract if events and handler are defined OR a reference to the name of contract defined globally at the top level",
          "type": "string"
        },
        "address": {
          "description": "A single address or a list of addresses to be indexed. This can be left as null in the case where this contracts addresses will be registered dynamically.",
          "$ref": "#/$defs/Addresses"
        },
        "start_block": {
          "description": "The block at which the indexer should start ingesting data for this specific contract. If not specified, uses the chain start_block. Can be greater than the chain start_block for more specific indexing.",
          "type": [
            "integer",
            "null"
          ],
          "format": "uint64",
          "minimum": 0
        },
        "abi_file_path": {
          "description": "Relative path (from config) to a json abi.",
          "type": "string"
        },
        "handler": {
          "description": "Optional relative path to a file where handlers are registered for the given contract. If not provided, handlers can be auto-loaded from src directory.",
          "type": [
            "string",
            "null"
          ]
        },
        "events": {
          "description": "A list of events that should be indexed on this contract",
          "type": "array",
          "items": {
            "$ref": "#/$defs/EventConfig"
          }
        }
      },
      "additionalProperties": false,
      "required": [
        "name"
      ]
    },
    "Addresses": {
      "anyOf": [
        {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "integer",
              "format": "uint",
              "minimum": 0
            }
          ]
        },
        {
          "type": "array",
          "items": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "integer",
                "format": "uint",
                "minimum": 0
              }
            ]
          }
        }
      ]
    }
  }
}