Local Development Quickstart

Purpose: Bootstrap a local Octant v2 contract-development environment. Audience: Developers setting up their Octant v2 development environment. Level: Beginner Source of truth: [email protected] Use this page when: you need repo setup, toolchain setup, and a first successful build or test run. Do not use this page for: a full end-to-end local deployment of the entire Octant stack.

Bootstrap Reality Check

• These setup paths require live access to GitHub, the Yarn registry, and Soldeer dependency sources. Treat DNS, proxy, and registry failures as setup blockers, not Solidity bugs.
• The public RPC values shipped in repo templates are placeholders for local exploration. Replace them with your own archive-capable endpoint before trusting fork-based failures.
• Cold-start audit environment for the recovery notes on this page: macOS, Forge 1.5.1-stable, Node v25.6.1, Yarn 4.9.2 in octant-v2-core, and Yarn 1.22.22 in octant-v2-strategy-foundry-mix.

This guide gets you from a clean machine to a working Octant v2 contract-development environment.

It covers two common Solidity-side paths:

1. Work inside octant-v2-core if you want to read, test, or extend the core protocol contracts.
2. Use the Yield Donating strategy starter template if you want the fastest path to a working YDS implementation.

If you are new to the docs, start here and then continue through the learning tracks.

Scope of this page

This page focuses on contract-side local setup.

For an overview of the strategy starter template and how it relates to the core repo, see Development Starter Pack.

Agent task card

Ask a coding assistant to follow this page in order, run each verification command before proceeding, and report the exact error when a step fails instead of guessing a fix.

Goal: Set up a working local development environment for Octant v2 strategy development Start repo: octant-v2-strategy-foundry-mix@ddd405c18bb0c765c0256ca952d4d9f4034cf3ec Core target pin: octant-v2-core@36ed6ad6665661a18f83394d561fa75c68ccf4ac (tag 1.2.0-develop.15)

Files to edit:

• .env.template → .env (Path A: octant-v2-core)
• .env.example → .env (Path B: starter template)
• Strategy contract and test files once you begin implementation (Path B)
• foundry.toml — add solc, evm_version, and/or [lint] lint_on_build = false if needed (Path B)

Files NOT to edit:

• dependencies/octant-v2-core/*

Required setup:

• Foundry Stable
• Node.js 22.16.0 or higher (Path A) / Node.js + Yarn Classic (Path B)
• Yarn
• A mainnet RPC endpoint with archive access (required for fork-based tests)
• Internet access to GitHub, the Yarn registry, and Soldeer dependency sources

Verification:

• forge --version prints a version number
• node --version prints v22.16.0 or higher
• forge soldeer install exits successfully before any build step
• forge build completes with no errors
• For Path A: forge test -vv runs after ETH_RPC_URL is set and mirrored to TEST_RPC_URL in .env
• For Path B: forge build completes after the starter-template compatibility fixes; fork tests require ETH_RPC_URL, TEST_ASSET_ADDRESS, and TEST_YIELD_SOURCE and should be run from the specific tutorial you are following

Do not:

• Skip verification commands
• Guess fixes for failed steps — report the exact error
• Modify files inside dependencies/octant-v2-core/
• (See also: Agent Anti-Patterns)

Source-of-truth rule

Use this order when local setup guidance appears to conflict:

1. the pinned [email protected] repo for contract behavior, dependencies, and current signatures,
2. the starter template repo for its own local scripts, Makefile targets, and test scaffolding,
3. this page for the recommended reading order and setup framing.

If a starter repository fails to build against the pinned core release, treat that as a version-alignment problem, not as proof that the core docs are wrong.

What this page covers

This page helps you:

• clone the relevant contract repos,
• install the required toolchain,
• build the contracts,
• run tests,
• start from the YDS starter template if that is your fastest path.

What this page does not cover

This page does not give you a single end-to-end recipe for deploying a complete Octant stack entirely from local contracts.

In particular, it does not walk through:

• deploying every shared implementation contract locally,
• wiring up a full vault-plus-strategy-plus-recipient topology from scratch,
• standing up a complete local version of the production deployment surface.

Treat this page as repo bootstrap + toolchain setup, then move into the track that matches your goal.

Version alignment

These docs are anchored to [email protected].

For the strategy-template workflow, this docs set targets octant-v2-strategy-foundry-mix@ddd405c18bb0c765c0256ca952d4d9f4034cf3ec. Treat that starter commit, together with [email protected], as the docs source of truth for the YDS quickstart and tutorials.

If you clone a different starter-template revision, re-validate its constructor signatures, test setup, submodule state, and dependency assumptions before trusting the walkthrough.

Prerequisites

Install the following first:

• Foundry Stable for both paths.
• Node.js 22.16.0 or higher if you are working inside octant-v2-core.
• Node.js plus Yarn Classic tooling if you are using the strategy starter template.

note

octant-v2-core explicitly pins a modern Node.js version in its own repo tooling. The starter template has a lighter JavaScript surface, but you still need Node and Yarn for its scripts and package management.

For the starter-template path in this docs set, use the tested snapshot octant-v2-strategy-foundry-mix@ddd405c18bb0c765c0256ca952d4d9f4034cf3ec rather than the default branch.

Choose a setup path

Path	Use it when	Primary output
octant-v2-core	you want to inspect protocol contracts, run the core test suite, or build directly in the main repo	a working local core-repo build and test environment
octant-v2-strategy-foundry-mix	you want the fastest route to a custom Yield Donating Strategy scaffold	a working starter-template build and fork-test environment

Path A: Work in octant-v2-core

Goal: confirm that you can build and test the pinned core repository locally.

Choose this path if you want to inspect protocol contracts, run the core test suite, or build directly against the main Octant v2 codebase. This path is best for code reading, experimentation, and implementation work inside the core repo, not for a turnkey local deployment of the whole protocol.

Inputs

• Foundry Stable
• Node.js 22.16.0+
• Yarn
• an RPC endpoint if you plan to use network-aware scripts

Files you will touch

• .env.template
• .env

Commands to run

1. Clone the repository

Command — clone octant-v2-core and enter the directory

git clone https://github.com/golemfoundation/octant-v2-core.git
cd octant-v2-core
git checkout 36ed6ad6665661a18f83394d561fa75c68ccf4ac
git rev-parse HEAD

The final command should print 36ed6ad6665661a18f83394d561fa75c68ccf4ac. Do not continue from the repository's default branch; these docs are pinned to that exact commit.

2. Install dependencies

First check whether Yarn already resolves to the repo's expected version:

Command — confirm your Yarn resolution

yarn --version

If that command already prints 4.9.2, skip corepack enable and continue directly to yarn install. Only run corepack enable if yarn is missing or resolves to a different version than the repo expects.

Command — install JavaScript tooling and Solidity dependencies

# Only run this if `yarn --version` did not already resolve to 4.9.2
corepack enable

yarn install
forge soldeer install

If corepack enable fails with EACCES or EPERM because it cannot write global shims such as /usr/local/bin/yarn, invoke the repository-pinned Yarn directly instead:

corepack yarn --version
corepack yarn install
forge soldeer install

The version command should print 4.9.2. This fallback does not install global shims and does not require write access to /usr/local/bin. Use corepack yarn run init in the next step when you are following this fallback.

What just happened? Soldeer is a Solidity package manager. This command pulled the Solidity libraries that Octant's contracts import — similar to how npm install pulls JavaScript packages.

Octant v2 uses yarn for JavaScript tooling and soldeer for Solidity dependencies.

Known issue — forge soldeer install panic on Forge 1.5.x on macOS

If forge soldeer install crashes with a panic that includes Attempted to create a NULL object, stop here. Treat that as a toolchain failure, not as a Solidity or docs bug. Capture your OS and forge --version, report the failure, and wait for a documented workaround or switch to a confirmed-good toolchain before continuing.

Until forge soldeer install exits successfully, forge build is not a meaningful next step because the dependency tree is still incomplete.

3. Set up local repo hooks

yarn run init

What just happened? This command ran the repo's initialization script and set up Git hooks that enforce code quality and formatting standards on every commit.

This runs the repo's init script and installs local Git hooks. Do not run bare yarn init from your shell, that is the Yarn package initializer and is not the same command.

If you used the direct-Corepack fallback above, run corepack yarn run init instead.

4. Copy the environment template

cp .env.template .env

5. Fill in the core repo environment variables

At minimum, the octant-v2-core workflow expects these values in .env:

Variable	When you need it	Description
RPC_URL	Recommended for most script and network-aware work	Default RPC endpoint used by scripts and network-aware tooling.
ETH_RPC_URL	Required before running forge test -vv	Canonical docs name for the mainnet RPC endpoint used for fork-based tests. In the pinned core repo, mirror it into TEST_RPC_URL because foundry.toml still maps the mainnet endpoint to that legacy variable name.
PRIVATE_KEY	Required for deployments and write operations	Private key used by deployment or admin scripts. Use a dedicated dev key, never a production signer.
ETHERSCAN_API_KEY	Required for verification flows	API key used for contract verification.

note

forge build does not require the full deployment-oriented environment, but the quickstart test command on this page does. If you plan to run forge test -vv, set ETH_RPC_URL first and mirror it to TEST_RPC_URL because the pinned core repo still reads the legacy name in foundry.toml.

Example .env fragment for Path A:

ETH_RPC_URL=https://eth-mainnet.g.alchemy.com/v2/YOUR_KEY
TEST_RPC_URL=${ETH_RPC_URL}

6. Build the contracts

forge build

What just happened? Foundry compiled all Solidity contracts in the repository and generated artifacts (ABIs and bytecode) that are necessary to deploy or test the contracts.

7. Run the tests

Before running the core test suite, make sure ETH_RPC_URL is populated in .env and mirrored to TEST_RPC_URL. The pinned core repo includes fork-based tests that create a mainnet fork via that legacy alias.

forge test -vv

Verify your setup

• forge --version prints a version number
• node --version prints v22.16.0 or higher
• forge build completes with no errors
• forge test -vv runs after ETH_RPC_URL is set and mirrored to TEST_RPC_URL

Expected output

• forge build completes successfully
• forge test -vv runs without local setup errors once ETH_RPC_URL is set and mirrored to TEST_RPC_URL
• you can now move into protocol-specific pages with a healthy local core repo

Common failure mode

If install succeeds but tests fail immediately, first check whether ETH_RPC_URL is missing, points to a non-working or non-archive RPC, or was not mirrored into TEST_RPC_URL for the current core repo. After that, verify that your Node version and Foundry version match the repo's expectations before debugging Solidity code.

Path B: Build a Yield Donating strategy with the starter template

Goal: confirm that you can build and fork-test the Yield Donating strategy starter template.

Choose this path if your goal is to implement a new Yield Donating strategy quickly, without starting from the full core repo.

Starter template inputs

• Foundry Stable
• Node.js
• Yarn Classic
• a mainnet RPC with archive access

Starter template files you will touch

• .env.example
• .env
• strategy contract and test files once you begin implementation

Starter template commands to run

1. Clone the tested starter-template snapshot

Command — clone the starter template and pin to the tested commit

git clone https://github.com/golemfoundation/octant-v2-strategy-foundry-mix.git
cd octant-v2-strategy-foundry-mix
git checkout ddd405c18bb0c765c0256ca952d4d9f4034cf3ec

This quickstart is written against that exact starter-template commit. Do not substitute the repo's default branch unless you are prepared to re-audit the constructor and test surfaces yourself.

2. Install starter template dependencies

The starter template bundles octant-v2-core as a Git submodule under dependencies/octant-v2-core/. The Solidity remappings resolve @octant-core/... imports into that directory, so the submodule must be present before anything will compile.

Command — install all JavaScript, Foundry, and Solidity dependencies and populate the core submodule

yarn --version            # expect 1.22.22 for the audited starter snapshot
yarn                      # install JavaScript tooling; this snapshot does not commit a yarn.lock
git submodule update --init --recursive   # populate the octant-v2-core submodule

What just happened? The starter template includes octant-v2-core as a Git submodule (a repo-inside-a-repo). This command populated that submodule so you have the actual Octant core contracts locally.

After dependency install, pin the bundled core submodule to the release these docs target:

git -C dependencies/octant-v2-core checkout 36ed6ad6665661a18f83394d561fa75c68ccf4ac

The submodule's default tracking branch is develop, while this docs set is anchored to [email protected]. Pinning it ensures your local build matches the contracts documented here.

Then install the remaining Solidity dependencies:

forge soldeer install

Starter-template reproducibility notes

• This audited starter snapshot does not commit a yarn.lock, so the first yarn run generates one locally and JavaScript dependency resolution can drift over time. The starter repo also gitignores yarn.lock, so it usually will not appear in git status.
• Do not run forge install for this starter snapshot. The Solidity dependencies are declared for Soldeer, and git submodule update --init --recursive already populates the only Git submodule.
• After you manually pin dependencies/octant-v2-core, expect git status to show a modified submodule. That local state is expected for this docs set.
• If you run git submodule update --init --recursive again later, it will reset the submodule back to the starter repo's recorded revision. Re-apply the manual pin after that reset, or run 09_agent_assisted_development/scripts/reconcile-starter-pin.sh from the starter repo root to restore both the submodule HEAD and the foundry.lock entry in one step.
• forge build can also re-run the submodule update when it detects missing dependencies (it prints Missing dependencies found. Installing now...). If you see that line, re-verify the core pin with git -C dependencies/octant-v2-core rev-parse HEAD before trusting build results — an un-pinned core can compile cleanly and hide the _symbol compatibility failure entirely.
• For a repeatable local re-pin plus optional lockfile reconciliation step, see Workflow Manifests and the companion helper script shipped with this docs bundle.

Known issue — forge soldeer install panic on Forge 1.5.x on macOS

If forge soldeer install panics before completion, stop and treat that as a toolchain blocker. Do not continue to forge build or make test; missing-import errors after a failed Soldeer step are still setup failures, not strategy-code bugs.

3. Copy the template environment file

cp .env.example .env

Replace the copied ETH_RPC_URL value before you trust any fork-test result. The audited starter template ships a public RPC URL as a placeholder, not as a validated archive endpoint for this workflow.

4. Fill in the starter-template environment variables

The strategy template uses a different set of environment variables than octant-v2-core.

Variable	When you need it	Description
ETH_RPC_URL	Required for fork-based strategy tests	Ethereum mainnet RPC endpoint. Must be set in .env. The Makefile reads it directly from that file and maps it to its internal FORK_URL variable used by the make test targets.
TEST_ASSET_ADDRESS	Required for strategy tests	ERC-20 address of the underlying asset used in your worked example or integration tests.
TEST_YIELD_SOURCE	Required for strategy tests	Address of the external protocol or vault your strategy integrates with.

Environment variable tips

If ETH_RPC_URL is set only in your shell and not written into .env, the template's Makefile will not pick it up for make test, make trace, and similar targets. The starter scaffold tests also read TEST_ASSET_ADDRESS and TEST_YIELD_SOURCE, so configure all three values before running broad starter tests. Use a mainnet RPC with archive access for fork-based strategy tests — standard non-archive nodes may fail if tests pin historical blocks. The template's .env.example also includes additional RPC variables such as FTM_RPC_URL, ARBI_RPC_URL, and others, but in the current starter template workflow only ETH_RPC_URL is materially used for the main fork-based strategy tests.

5. Reconcile the template with the pinned core revision

Before treating the template as a working baseline, verify that it still matches the core release you are targeting.

For publication of this docs set, the intended baseline is:

• octant-v2-strategy-foundry-mix@ddd405c18bb0c765c0256ca952d4d9f4034cf3ec
• [email protected]

At that tested combination, one known compatibility point is that the strategy template must pass the current _symbol parameter through the BaseStrategy constructor and match the updated ITokenizedStrategy.initialize() signature. This affects four files, the strategy contract, the factory, and two test files. Apply the full reconciliation described in the Hello World Strategy — Compatibility note before proceeding.

The same reconciliation should update first-deposit test expectations for 1.2.0-develop.15: empty YDS deposits seed 1_000 locked shares at address(0xdead), so a first depositor receives assets - 1000 shares rather than an exact 1:1 share amount.

Solidity version gap

[email protected] compiles with Solidity 0.8.33 targeting the Prague EVM. The starter template compiles with Solidity 0.8.25 and does not specify an EVM target. If you copy code from the core repo into the template, you may hit compilation errors from newer language features or opcodes that the 0.8.25 compiler does not support.

Action: If you need to copy code from octant-v2-core into the starter template, add solc = "0.8.33" and evm_version = "prague" to the [profile.default] section of the template's foundry.toml.

Recommended reference pages:

• Hello World Strategy
• How to Create a YieldDonating Strategy

6. Run the template tests

The starter template's broad scaffold tests require concrete ETH_RPC_URL, TEST_ASSET_ADDRESS, and TEST_YIELD_SOURCE values. Treat forge build as the compatibility checkpoint after the _symbol fixes; run tests from the tutorial you are following once it gives you concrete strategy code and assertions.

Common commands in the starter template are:

Command — run the starter template test suite

make -B test                                       # force-run the full test suite
make -B test-contract contract=YourStrategyTest    # force-run a specific test file
make -B trace-contract contract=YourStrategyTest   # force-run a specific test file with full call traces
make -B trace                                      # force-run the full test suite with higher verbosity

The -B flag matters once your workspace contains a top-level test/ directory, because this starter snapshot's Makefile does not mark its test target as phony. Without -B, make test can decide the directory is already up to date and skip the Forge command.

Starter template expected output

• the starter template builds after any required compatibility reconciliation
• tutorial-specific fork tests run with your configured ETH_RPC_URL, TEST_ASSET_ADDRESS, and TEST_YIELD_SOURCE
• you have a working base for YDS-specific implementation work

Starter template common failure mode

If the repo installs cleanly but forge build still fails, check for template drift against the pinned core revision before debugging your own changes.

Forge ≥ 1.5 lint-on-build note: If forge build fails with errors about unresolved src/... imports inside the core submodule (even after applying the _symbol compatibility fixes), your Forge version is running its linter during build. The linter cannot resolve the core submodule's internal import paths from the parent project context. Add the following top-level section to your foundry.toml:

Fragment — top-level foundry.toml section

[lint]
lint_on_build = false

Then re-run forge build. This disables lint during compilation without affecting correctness. See foundry-rs/foundry#12721 for background.

First-Error Routing Table

Use the first setup error you hit to decide whether to keep going or stop and fix the environment first.

First error fingerprint	Class	Next action
EPERM: operation not permitted, symlink ... /usr/local/bin/pnpm during corepack enable	tooling	If yarn --version already matches the repo expectation, skip corepack enable. Otherwise fix Yarn or Corepack outside the repo before continuing.
Attempted to create a NULL object during forge soldeer install	tooling	Stop and report the Forge or Soldeer toolchain bug. Do not continue to forge build.
getaddrinfo ENOTFOUND registry.yarnpkg.com or Could not resolve host: github.com	network	Restore DNS, proxy, or internet access to GitHub and the package registries, then rerun the same setup step.
Fork creation fails, or tests complain about missing archive state	RPC	Replace the template RPC value with your own archive-capable endpoint in .env, then rerun the test.
Source "... not found" immediately after a failed dependency install	tooling	Treat it as incomplete dependencies, not as a code issue. Get forge soldeer install to finish before debugging imports.
Signature mismatch or compatibility-note failure after dependencies are present	docs drift	Compare against the pinned repos and apply the documented compatibility fixes before changing tutorial code.
Existing starter scaffold tests fail after installs succeed, pins match, compatibility fixes are applied, and forge build passes	starter scaffold	Do not rewrite the pinned core submodule to satisfy old placeholder assertions. Run the tutorial-specific tests for the strategy you are building, or reconcile the starter tests separately with concrete test asset/yield-source assumptions.
Compiler or tutorial-specific test failure after installs succeed, pins match, and compatibility fixes are applied	code issue	Debug the strategy or test logic itself; at that point the setup layer has already passed.

Which path should you choose?

Choose octant-v2-core when you want to:

• understand the protocol contracts in depth,
• work on shared core code,
• read or extend factories, mechanisms, vaults, and regen contracts,
• build YSS or TAM implementations directly in the main codebase.

Choose the starter template when you want to:

• build a Yield Donating strategy quickly,
• work from a narrower scaffold,
• focus on _deployFunds, _freeFunds, and _harvestAndReport rather than the entire protocol.

If your real goal is "deploy a complete Octant stack locally from scratch", the current docs do not yet provide a single canonical recipe for that. Use the setup steps here, then continue with:

• Developer Orientation
• Common Developer Workflows
• Reading the Smart-Contract Reference

Common gotchas

"My fork tests fail even though my unit tests pass."

Check your RPC. Fork-based tests often need a mainnet endpoint with archive access.

"I copied variables from one repo and another repo still fails."

That is expected. octant-v2-core and octant-v2-strategy-foundry-mix do not use the same environment variable names. Treat them as separate workflows.

"Do I need deployment credentials just to read the code and run basic tests?"

Usually not. For many local tasks, build and read-only test flows are enough. Deployment-specific variables matter once you start using scripts that sign transactions or verify contracts.

"Why does the starter template still fail after install?"

First confirm that you are on the tested starter-template commit and that dependencies/octant-v2-core is pinned to 1.2.0-develop.15. After that, check the strategy tutorial pages for the required _symbol compatibility fixes before assuming your local environment is broken.

Next steps

Now choose the track that matches your goal:

• Build a Yield Donating Strategy: How to Create a YieldDonating Strategy
• Build a Yield Skimming Strategy: Introduction to YSS
• Build a Tokenized Allocation Mechanism: Tokenized Allocation Mechanisms
• Understand the overall dev surface first: Developer Orientation
• Learn more about the strategy starter template: Development Starter Pack