Configuration & Environment Variables

Relevant source files

The following files were used as context for generating this wiki page:

• apps/backend/src/config/app.config.ts
• apps/backend/src/config/database.config.ts
• apps/backend/src/config/starknet.config.ts
• apps/data-processing/README.md
• apps/backend/README.md
• apps/dojo/dojo_dev.toml
• apps/dojo/dojo_release.toml
• apps/dojo/README.md
• apps/backend/src/starknet/starknet.service.ts

Configuration in the OnChain Sage project is managed through a combination of environment variables (.env files) and strongly-typed configuration files. This approach provides flexibility for different deployment environments (development, production) while ensuring type safety and maintainability. The configuration is segmented by application, with distinct setups for the NestJS backend, the Dojo smart contracts, and the Python-based data processing services.

The backend leverages the @nestjs/config module to load environment variables and expose them through dedicated configuration services. The Dojo contracts use .toml files to define environment-specific parameters for local development (Katana) and mainnet deployments. This modular configuration strategy is crucial for the project's multi-component architecture, allowing each service to be configured independently.

Backend Configuration (apps/backend)

The backend service, built with NestJS, centralizes its configuration management within the apps/backend/src/config/ directory. It uses environment-specific .env files (e.g., .env.development) to store sensitive data and environment-dependent values.

Sources: apps/backend/README.md

Configuration Loading Flow

The NestJS ConfigModule is responsible for parsing the .env file and making the variables available to the application. Typed configuration files then map these string values to structured, type-safe objects that can be injected into different services.

The following diagram illustrates the flow of configuration data in the backend:

Environment Variables

The backend relies on a set of environment variables defined in a .env file. A template is provided in .env.development.example.

Variable	Description	Used In
NODE_ENV	The application environment (e.g., development).	app.config.ts
PORT	The port on which the backend server will run.	app.config.ts
DATABASE_HOST	Hostname of the PostgreSQL database.	database.config.ts
DATABASE_PORT	Port of the PostgreSQL database.	database.config.ts
DATABASE_USER	Username for the database connection.	database.config.ts
DATABASE_PASSWORD	Password for the database connection.	database.config.ts
DATABASE_NAME	The name of the database to use.	database.config.ts
JWT_SECRET	Secret key for signing JWT tokens.	auth/auth.module.ts (implied)
JWT_EXPIRATION	Expiration time for JWT tokens (e.g., 24h).	auth/auth.module.ts (implied)
STARKNET_NODE_URL	The RPC URL for the Starknet node.	starknet.config.ts
POST_SYSTEM_CONTRACT	Address of the PostSystem smart contract.	starknet.config.ts
BADGE_SYSTEM_CONTRACT	Address of the BadgeSystem smart contract.	starknet.config.ts
TORII_URL	The URL for the Torii indexer service.	starknet.config.ts

Sources: apps/backend/README.md, apps/backend/src/config/app.config.ts, apps/backend/src/config/database.config.ts, apps/backend/src/config/starknet.config.ts

Typed Configuration Files

Application Configuration

app.config.ts handles general application settings.

// apps/backend/src/config/app.config.ts:3-9
export const appConfig = () => ({
  env: process.env.NODE_ENV || 'development',
  port: parseInt(process.env.PORT, 10) || 3000,
  jwt: {
    secret: process.env.JWT_SECRET,
    expiresIn: process.env.JWT_EXPIRATION || '24h',
  },
});

Sources: apps/backend/src/config/app.config.ts:3-9

Database Configuration

database.config.ts provides the configuration for the TypeORM connection to the PostgreSQL database.

// apps/backend/src/config/database.config.ts:3-12
export const databaseConfig = () => ({
  type: 'postgres',
  host: process.env.DATABASE_HOST,
  port: parseInt(process.env.DATABASE_PORT, 10) || 5432,
  username: process.env.DATABASE_USER,
  password: process.env.DATABASE_PASSWORD,
  database: process.env.DATABASE_NAME,
  entities: [__dirname + '/../**/*.entity{.ts,.js}'],
  synchronize: process.env.NODE_ENV !== 'production', // Be cautious with this in production
});

Sources: apps/backend/src/config/database.config.ts:3-12

Starknet Configuration

starknet.config.ts manages settings for interacting with the Starknet blockchain and its contracts.

// apps/backend/src/config/starknet.config.ts:3-12
export const starknetConfig = () => ({
  starknet: {
    nodeUrl: process.env.STARKNET_NODE_URL,
    contracts: {
      postSystem: process.env.POST_SYSTEM_CONTRACT,
      badgeSystem: process.env.BADGE_SYSTEM_CONTRACT,
    },
  },
  torii: {
    url: process.env.TORII_URL,
  },
});

This configuration is consumed by StarknetService to initialize the provider and contract instances.
Sources: apps/backend/src/config/starknet.config.ts:3-12, apps/backend/src/starknet/starknet.service.ts:15-17

Dojo Smart Contract Configuration (apps/dojo)

The Dojo project uses TOML files for configuration, separating settings for development and release environments.

Sources: apps/dojo/README.md

Environment-Specific Files

• dojo_dev.toml: Used for local development, typically connecting to a Katana node.
• dojo_release.toml: Used for production deployments, connecting to the Starknet mainnet.

The following diagram shows how the deployment environment determines which configuration is used.

Configuration Structure

Both dev and release TOML files share a similar structure.

Section	Key	Description	Example (dev)	Example (release)
[world]	name	The name of the Dojo world.	"OnChain Sage"	"OnChain Sage"
[world]	seed	A unique seed for the world generation.	"onchainsage_dev"	"onchainsage_mainnet"
[env]	rpc_url	The RPC endpoint for the Starknet node.	"http://localhost:5050/"	"https://starknet-mainnet.infura.io/v3/"
[env]	account_address	The deployer account address.	0x127...cfcec	Set via env var
[env]	private_key	The private key for the deployer account.	0xc5b...f912	Set via env var
[writers]	"onchainsage"	A list of contracts granted writer permissions.	["onchainsage-actions", ...]	["onchainsage-actions", ...]

Sources: apps/dojo/dojo_dev.toml, apps/dojo/dojo_release.toml

CI/CD Secrets

For automated deployments, the Dojo project expects GitHub secrets to be configured. These secrets provide the necessary credentials for deploying to testnet and mainnet environments.

Testnet Secrets:

• TESTNET_RPC_URL
• TESTNET_ACCOUNT_ADDRESS
• TESTNET_PRIVATE_KEY

Mainnet Secrets:

• MAINNET_RPC_URL
• MAINNET_ACCOUNT_ADDRESS
• MAINNET_PRIVATE_KEY

Sources: apps/dojo/README.md

Data Processing Configuration (apps/data-processing)

The data processing service, written in Python, also follows a modular configuration approach. The apps/data-processing/README.md indicates the presence of a config/ directory for configuration files and settings. While specific environment variables are not detailed, the structure implies that pipeline parameters, model settings, and client configurations are managed here.

Sources: apps/data-processing/README.md