fogo-dev-env (working title)

Developer-focused Solana test validator that preloads the full fogo-sessions stack and exposes a permissive paymaster for local experiments.

Project Goal

Deliver a "one-button" local developer experience for the Fogo Sessions standard:

1. Clone this repo (which embeds the upstream fogo-sessions codebase via git submodule).
2. Run docker compose up.
3. Receive a solana-test-validator instance running locally with Sessions programs deployed, bootstrap scripts executed (domain registry, tollbooths, sponsor accounts), and an "accept everything" paymaster sponsoring transactions for any connected dApp.

Status

The repository is still in the bootstrapping phase, but key scaffolding already exists:

• AGENTS.md and prompts/AttackPlan.md document the high-level product vision and milestones.
• NEXT_STEPS.md lays out the concrete implementation checklist.
• The upstream fogo-sessions repo is vendored as a git submodule under core/.
• docker/validator now uses solanafoundation/solana-verifiable-build:2.2.20 for both build and runtime stages: the first stage runs cargo build-sbf for every fogo program, and the second stage reuses the same image to run solana-test-validator with the compiled artifacts plus SPL Token preloaded.
• docker/paymaster builds a tiny Rust HTTP service (using the nightly Rust base image inside the container to satisfy edition-2024 deps) that exposes /sign-and-send.
• The initializer container installs the core/scripts/ts workspace with pnpm, sets the chain ID, registers the default domain/program, initializes tollbooth recipients, registers fee config, and funds the demo sponsor addresses using the baked faucet keypair.

Current Tasks

1. Docs & DX: Keep expanding README.md, docs/, .env.example, and add troubleshooting/backlog notes as pieces land (CLI wrapper, Postgres/full-fidelity mode, testing).

Quickstart (Placeholder)

git submodule update --init --recursive

# copy default env if needed
./scripts/setup-env.sh

# if you previously created .env, ensure FAUCET_KEYPAIR/PAYMASTER_SPONSOR_KEYPAIR
# point to /opt/fogo/keys/*.json so the baked-in keys are accessible inside containers.

# build + run the stack (validator preloads Sessions programs)
docker compose up --build

The validator image build will download the Solana toolchain, compile all fogo-sessions programs, and preload them into solana-test-validator. The paymaster service (paymaster/) is a small Rust HTTP server that signs any transaction (fee payer = dev sponsor) via /sign-and-send. The initializer seeds the local chain (chain ID, domain registry, tollbooth, fee config, sponsor funding) using the baked faucet keypair.

Sessions IDL Artifacts

Anchor IDLs and the generated TypeScript bindings for the Sessions programs are committed under artifacts/sessions-idls/src/{idl,types}. The Docker build copies these files into the core/packages/sessions-idls/src tree before compiling the TypeScript bootstrap scripts, so we no longer run anchor idl build on every Docker build/startup. If you bump the core/ submodule to a commit that changes the on-chain programs, regenerate the artifacts with the helper script and commit the results alongside the submodule pointer:

# build the idl-builder image once (use --platform on Apple silicon)
docker build --platform linux/amd64 -f docker/idl-builder/Dockerfile -t fogo-dev-idl-builder:latest .
# regenerate artifacts with the helper
./scripts/build-idls.sh
git status artifacts/sessions-idls

The script uses a dedicated docker/idl-builder image (Solana toolchain + Anchor + pnpm) so it doesn’t modify core/ or install anything on your host. If the artifacts folder is empty, the Docker build falls back to generating the IDLs inside the scripts stage, but that defeats the faster-build goal, so keep the committed artifacts up to date.

Registering Additional Domains / Programs

The initializer automatically registers http://localhost:3000 to the example program, but you can add more mappings at any time (as long as docker compose up is running) via the helper script:

./scripts/register-domain.sh <PROGRAM_ID> [domain]
# example: ./scripts/register-domain.sh Examtz9qAwhxcADNFodNA2QpxK7SM9bCHyiaUvWvFBM3 http://localhost:4000

domain defaults to http://localhost:3000. The script execs into the running validator container and runs the existing domain-registry add CLI using the baked faucet keypair (/opt/fogo/keys/faucet.json) and RPC URL http://127.0.0.1:8899. Override SOLANA_RPC_URL, DOMAIN, or FAUCET_KEYPAIR_PATH in the environment if you need different values.

Smoke Test

Once docker compose up reports that the validator and paymaster are healthy, you can run a one-shot smoke test that submits a transfer via the paymaster and waits for confirmation:

docker compose --profile smoke run --rm smoke-test

This command starts a temporary Node container, installs @solana/web3.js, builds a transfer transaction (sponsor → sponsor), posts it to the paymaster, and polls the validator RPC until the signature is confirmed. A successful run prints the resulting signature; any failure will surface the paymaster/RPC error for debugging.

Initializer Configuration

The initializer is now fully automated:

• scripts/bootstrap.sh runs the TS CLIs with baked defaults (chain ID, domain URL/program, tollbooth mints, fee config, sponsor addresses) using the faucet keypair. Adjust the defaults via .env if needed.
• Dependencies are pulled during docker build via pnpm fetch --filter "@fogo/scripts...", and container startups run pnpm install --offline only if node_modules is missing.
• If you bump core/, rebuild the validator/initializer images to refresh the cached dependencies.