`sunscreen.yml` schema

Single source of truth for a workspace. Generated by chain new, read by every other command.

Warning

This page summarizes the schema. The authoritative shape lives in src/config/schema.rs and is emitted as JSON Schema via schemars. When in doubt, the Rust types win.

## Top-level shape

version: 1

project:
  name: my-app
  framework: anchor         # anchor | pinocchio
  frontend: vite            # none | vite | next

toolchain:
  # tool version pins; see ToolchainCfg in schema.rs
  anchor: "^0.30"

scaffolding:
  # marker + scaffolder preferences; see ScaffoldingCfg

programs:
  - name: my_app
    path: programs/my_app
    program_id: ~           # filled by deploy

workspace:
  # workspace-level layout knobs

clusters:
  localnet:
    url: http://127.0.0.1:8899
    wallet: ~/.config/solana/id.json
  devnet:
    url: https://api.devnet.solana.com
    wallet: ~/.config/solana/id.json
  mainnet:
    url: https://api.mainnet-beta.solana.com
    wallet: ~/.config/solana/id.json

runtime:
  engine: surfpool          # surfpool | test-validator
  port: 8899
  faucet_sol: 100

plugins:
  - source: ./plugins/my-plugin
    version: "0.2.0"

Top-level keys

Key	Type	Required	Description
`version`	int	yes	schema version; sunscreen migrates older values automatically
`project`	object	no	`name`, `framework` (`anchor`/`pinocchio`), `frontend` (`none`/`vite`/`next`)
`toolchain`	object	no	external tool version pins
`scaffolding`	object	no	scaffolder/marker behaviour knobs
`programs`	array	no	one entry per program in the workspace
`workspace`	object	no	workspace-level layout
`clusters`	object	no	per-cluster RPC + wallet (`localnet`/`devnet`/`mainnet`)
`runtime`	object	no	local dev runtime preferences
`plugins`	array	no	declared plugins

`programs[]`

Field	Type	Required	Description
`name`	string	yes	snake_case program name
`path`	path	yes	relative to workspace root
`program_id`	string	no	filled by `deploy`; `null` until first deploy

`clusters.<name>`

Field	Type	Required	Description
`url`	string	yes	RPC endpoint
`wallet`	string	yes	path to the default keypair for this cluster

Sunscreen ships defaults for localnet, devnet, and mainnet. The CLI accepts mainnet (not mainnet-beta) as the cluster target name; the underlying URL remains https://api.mainnet-beta.solana.com.

`runtime`

Field	Type	Default	Description
`engine`	enum	`surfpool`	`surfpool` or `test-validator` (sunscreen falls back from Surfpool to test-validator when Surfpool isn't on PATH)
`port`	int	`8899`	validator RPC port
`faucet_sol`	int	`100`	seed balance for the local runtime faucet

`plugins[]`

Field	Type	Required	Description
`source`	string	yes	local path or git URL
`version`	semver	yes	with or without `v` prefix

Migrations

When sunscreen reads a sunscreen.yml with a lower version than the current binary supports, it migrates in-place. Migrations are deterministic.

Validation

sunscreen.yml is validated on every command. Failures exit with code 3 (invalid_config) and a message naming the offending field path.