Skip to main content

Environment Configuration Variables

The following is a list of possible environment variables that can be configured for your project. These variables are read in the ENV class, located in @paima/utils/config.js. Please refer to that file for more information on default values.

Funnel Configuration​

These these variables are used if you only need to synchronize a single network for your application. If you need to synchronize multiple networks, learn more about funnel configuration here

Required variables​

  • Chain variables:
    • CHAIN_URI: The URI of the chain.
    • CHAIN_EXPLORER_URI: The URI of the chain explorer.
    • CHAIN_ID: The ID of the chain.
    • CHAIN_NAME: The name of the chain.
  • Chain currency variables:
    • CHAIN_CURRENCY_NAME: The name of the chain currency.
    • CHAIN_CURRENCY_SYMBOL: The symbol of the chain currency.
    • CHAIN_CURRENCY_DECIMALS: The number of decimals for the chain currency.
  • CONTRACT_ADDRESS: The address of your Paima L2 contract.
  • START_BLOCKHEIGHT: The block height at which the syncing process starts. This is usually the block height at which the contract was deployed.
  • BLOCK_TIME: The number of seconds it takes for new blocks to be created on the chain you deployed your L2 contract on.

Optional variables​

  • Primitive Catalogue:
    • DEFAULT_PRESYNC_STEP_SIZE: number of blocks to process in each step during initial presync phase. If not provided, a value of 1000 is used. Generally no need to change this value.
    • CDE_CONFIG_PATH: allows you to specify a custom location for your extensions.$NETWORK.yml that is used to initialize primitive catalogue entries
  • Cardano extensions
    • CARP_URL: The URL of a Carp instance, required when using Cardano primitives.
    • CARDANO_NETWORK: One of preview, preprod, mainnet. It needs to match the network indexed by the Carp instance.
    • DEFAULT_FUNNEL_GROUP_SIZE: The number of blocks queried in one funnel sync step. If not set, a value of 100 is used. Generally no need to change this value.

Others​

Required variables​

  • Database connection variables (self explanatory):
    • DB_USER
    • DB_PW
    • DB_NAME
    • DB_HOST
    • DB_PORT
  • BACKEND_URI: The URL of where your game node server will be deployed. This is used by the Middleware to interact with your game node.
  • WEBSERVER_PORT: The port to use for running your game node server.

Optional Variables​

This section includes optional environment variables that have sensible default values if not explicitly set.

  • BATCHER_URI: The URL of the deployed batcher, if used.

  • DEFAULT_FEE: The blockchain fee to be set in transactions created by the Middleware.

  • ENABLE_DRY_RUN: Adds a GET /dry_run endpoint for input testing. Use it to post game inputs to validate them without modifying the game state.

  • NETWORK: Used across modules to determine which .env file to read (.env.$NETWORK). Must be set separately if needed.

  • FORCE_INVALID_PAIMA_DB_TABLE_DELETION: Instead of failing during DB initialization, it deletes invalid tables and recreates them (without the previous content). If turned off, resync from scratch is needed after a major @paima/sdk update that affects internal tables.

  • STORE_HISTORICAL_GAME_INPUTS: If enabled, one of the internal tables stores all of the posted game inputs. Note that the table is currently accessible only through a direct DB connection.

  • POLLING_RATE: The frequency at which to check for new block data. If not filled in, a value of BLOCK_TIME - 0.1 is used.

  • STOP_BLOCKHEIGHT: The block at which the funnel stops syncing. This can be useful during development or tests.

  • SERVER_ONLY_MODE: Set this to run the game node without syncing new blocks.

  • Security variables:

    • CONCISE_GAME_NAME: This value will be prefixed to each concise command sent and should be a unique string for each game. E.g., "TDWOTJ" for Tower Defense: Wrath of the Jungle. This prevents replay attacks between different games. This is a mandatory requirement for Gaming Accounts Automatic Signing.

  • GAME_NODE_VERSION: defined statically in @paima/sdk. Check used to ensure your game node is running with a compatible version of paima-engine. After a major upgrade and necessary adjustments, you should adjust the version on your side.

Customization​

You can extend the ENV class in your game to add your own game variables. Here's an example snippet:

export class GameENV extends ENV {
  static get LONG_CONFIG(): string {
    return process.env.LONG_CONFIG || "default";
  }
}

Example config file​

## CHAIN DATA
# Example: "https://rpc-devnet-cardano-evm.c1.milkomeda.com"
CHAIN_URI=""
# Example: "https://explorer-devnet-cardano-evm.c1.milkomeda.com"
CHAIN_EXPLORER_URI=""
# Example: "Milkomeda C1 Testnet"
CHAIN_NAME=""
# Example: "200101"
CHAIN_ID=""
# Note: The shorthand currency name/symbol shown in the user's wallet
# Example: "mtADA"
CHAIN_CURRENCY_SYMBOL=""
# Note: The number of decimals of the native/gas asset of the chain
# Example: "18"
CHAIN_CURRENCY_DECIMALS=""
# Note: This is in seconds as a float
# Example: "2.0"
BLOCK_TIME=""

## SECURITY
# Unique Game Security Prefix
# Example: "MyGame"
CONCISE_GAME_NAME=""

## CONTRACT DEPLOYMENT
# Example: "0xA02F7744868945A346Ee6994068F54D039683445"
CONTRACT_ADDRESS=""
# Note: This is the block height to start syncing from; usually the contract deployment block height
# Example: "9000000"
START_BLOCKHEIGHT=""

## Middleware
# Note: This is the URL which your middleware will use to interact with your game node webserver
# Example: "http://localhost:3333"
BACKEND_URI=""

## MISC
# Note: This is the port your game node webserver will use
# Example: "3333"
WEBSERVER_PORT=""
# Note: This enables running your game node with just the webserver running, meaning no new blocks will be synced.
# This is primarily useful for development, devops, or testing other edge cases where you want to interact with
# the game node but not have the game state progress forward.
SERVER_ONLY_MODE="false"

## DATABASE
DB_NAME="postgres"
DB_USER="postgres"
DB_PW="postgres"
DB_HOST="localhost"
DB_PORT="5432"

# NFT
# Note: This is the address of the native nft sale proxy contract
# Example: "0xbD9e6bA880d6302A0B93456308a5A998Ffd8eb5E"
NATIVE_NFT_SALE_PROXY=""

Cardano​

BATCHER_CARDANO_ENABLED_POOLS="095dd39da2d8534f9ddb93759a1931288e5dd79ae04fa5914e157bd6,093de39da2d8534f9ddb93759a1931288e5dd79a404fa5914e157b99"
BATCHER_CARP_URL=http://127.0.0.1:3000

CARP_URL=http://127.0.0.1:3000
CARDANO_NETWORK=preview
CARDANO_CONFIRMATION_DEPTH=10