Requires fsc-evm v4.0.0+

1. Overview
2. Key Macros
3. Querying Variables
4. Modifying Variables
5. Standardized Naming Conventions

The fsc-evm package is powered by a novel variable management system that enables Flipside to scale data support across multiple EVM (Ethereum Virtual Machine) blockchains while adhering to DRY (Don't Repeat Yourself) principles. While dbt offers its own native var() function, fsc-evm implements a custom get_var() function with enhanced capabilities for managing variables across projects more efficiently.

The variable management system in fsc-evm consists of three main components:

1. Project-specific variable definitions stored in separate files (e.g., .../project_vars/mantle_vars.sql)
2. Core variable retrieval macros that collect, process, and return variables (e.g., '../variables/get_vars.sql)
3. Configuration macro that sets all variables on a namespace (e.g., '../variables/return_vars.sql)

This structure allows for consistent variable management across different blockchain projects while accommodating project-specific requirements.

• Retrieves variable configurations from project-specific macros (e.g., .../project_vars/mantle_vars.sql)
• When all_projects=True, gets variables from all projects
  • Otherwise, gets variables only for the current project based on target database
• Returns a nested dictionary structure of all variables

• Converts the nested variable structure from vars_config() into a flat list of dictionaries
• Each dictionary contains project, key, parent_key, and value properties
• Used internally by get_var() to process variable relationships

• Logs variable information to the terminal and the table fsc_evm.admin._master_keys
• Only runs when WRITE_VARS_ENABLED is set to true
• Records details such package, category, variable_key, default_value, and default_type
• This is the master list of available variables which is useful for processes that involve setting variables, managing projects and debugging.

• Main function to retrieve variables by key with support for default values
• Supports various data types including STRING, ARRAY, JSON, VARIANT, OBJECT, NUMBER, INTEGER, FIXED, FLOAT, DECIMAL, BOOLEAN
• Provides mapping/dictionary support for Parent-Child key relationships
• Backwards compatible with dbt native var() function
  • Variables can continue to be defined in dbt_project.yml if necessary
  • Defaults to existing variables in dbt_project.yml if not found in project configs
  • get_var() utilizes similar input parameter structure and rules as var()`.
• Performs type conversion based on the value format

• Sets and returns all configurable variables used throughout the project
• Organizes variables by category (Global, Bronze, Silver, Streamline, Decoder, etc.)
• Each variable must be "set" with ns.variable_key = get_var(...) logic to be accessible
  • Each variable must include a default value
  • Creates a namespace that can be referenced in models and other macros
• Can be used with write_vars() to log all variables by running dbt run-operation return_vars --vars '{"WRITE_VARS_ENABLED": true}'

• Define database or project-level configuration values
• Return dictionary objects with key-value pairs
• Allow for customization of variables per project

This variable management system provides a flexible, type-safe, and scalable approach to managing configuration across multiple blockchain projects within the fsc-evm framework.

Source of truth for project variables

SELECT *
FROM fsc_evm.admin._master_keys;

-- Contains one row for every available variable
-- All available variables must be set in `return_vars(). New additions or modifications are inserted it this table via the dbt_run_master_keys workflow / command `dbt run-operation return_vars --vars '{"WRITE_VARS_ENABLED": true}'`

Dimensional, Fact & EZ Tables at the Project or Database level

SELECT *
FROM <database>.admin.dim_variables;
-- Dimensional view for querying the "latest" versions of the master keys

SELECT *
FROM <database>.admin.fact_variables;
-- Contains all variables defined in the project specific variable config files found at `macros/global/variables/project_vars`

SELECT *
FROM <database>.admin.ez_variables;
-- Joins dim / fact on key or parent_key
-- Note, if a variable exists in the fact view (project-level config) and does not exist in the dim view (master keys), the variable is considered "not set" and must first be "set" in `return_vars()` for proper usage in `fsc-evm`

1. To add or modify the project variables, simply modify the project-level files at macros/global/variables/project_vars;

   • For new projects: create a new <project>_vars.sql file with a new <project>_vars() macro containing applicable variables. Please reference fsc_evm.admin.dim_variables for a complete list of available variables.
   • For existing projects: modify the variables in the applicable <project>_vars.sql file and subsequent <project>_vars() macro.

2. If any variable is new or does not yet exist in return_vars(), please set the variable in return_vars() for proper usage in fsc-evm and downstream projects.

[PACKAGE]_[CATEGORY?]_[ENTITY?]_[PROPERTY?]_[ACTION?]

• ? == optional
• PACKAGE: Required. Package name with _PACKAGE excluded. Use GLOBAL if spans multiple packages.
  • Examples: MAIN, DECODER, CURATED
• CATEGORY: Optional. Functional area. Omit if variable applies across multiple categories.
  • Examples: PRICES, ABIS, SILVER, SL (streamline, see "Abbreviations" below)
• ENTITY: Optional. Specific model/subcategory/component being configured. Omit if variable applies across multiple entities.
  • Examples: RECEIPTS, DECODED_LOGS, TRACES_COMPLETE
• PROPERTY: Optional. The column name, characteristic, feature or aspect of the package, category or entity being configured.
  • Examples: BLOB_BASE_FEE, NODE_SECRET_PATH, FULL_REFRESH, TESTING_LIMIT, PRODUCER_BATCH_SIZE
• ACTION: Optional. The specific operation or modifier for the property. Omit when the PROPERTY itself fully describes the configuration without needing additional qualification.
  • Examples: ENABLED, DISABLED

Abbreviations:

• Any abbreviations must be used sparingly, as Variables may be constructed or referenced dynamically and sometimes require full non-abbreviated names. Unapproved usage of abbreviations may result in breaking changes.
• Approved abbreviations include;
  • Package names → _PACKAGE can be omitted. E.g. MAIN_PACKAGE → MAIN
  • STREAMLINE → SL
  • OBSERVABILITY → OBSERV
  • FULL_REFRESH → FR

Full Variable KEY Examples:

• GLOBAL_NODE_VAULT_PATH
  • Comprised of: [PACKAGE]_[PROPERTY]
• MAIN_CORE_RECEIPTS_BY_HASH_ENABLED
  • Comprised of: [PACKAGE]_[CATEGORY]_[ENTITY]_[ACTION]
• MAIN_SL_RECEIPTS_REALTIME_SQL_LIMIT
  • Comprised of: [PACKAGE]_[CATEGORY]_[ENTITY]_[PROPERTY]
• DECODER_SL_CONTRACT_ABIS_EXPLORER_URL
  • Comprised of: [PACKAGE]_[CATEGORY]_[PROPERTY]

Note: These standards also apply to variables with PARENT_KEY functionality enabled. If PARENT_KEY is not NULL, KEY == some_value

• Example:
  • PARENT_KEY :CURATED_VERTEX_TOKEN_MAPPING
  • KEY: USDC, wMNT, WETH