Skip to main content

Development Starter Pack

Purpose: Explain what the Octant v2 strategy starter repository is for, and where it stops. Audience: Developers choosing between the strategy starter template and the full core repo. Level: Beginner

Before you read this page

Source of truth: [email protected] for contract architecture, the starter repo for its own local files and scripts. Use this page when: you need to decide whether to use the strategy starter template or work directly in core, and you want to understand how much you can safely trust the starter's bundled assets. Do not use this page for: exact contract behavior or a complete production deployment guide.

Bootstrap Reality Check
  • This starter workflow requires live access to GitHub, the Yarn registry, and Soldeer dependency sources.
  • The audited starter snapshot does not commit a yarn.lock, so your first local yarn run will generate one and JavaScript resolution can drift over time.
  • Cold-start audit environment for the reproducibility notes below: macOS, Forge 1.5.1-stable, Node v25.6.1, Yarn 1.22.22, and octant-v2-core manually re-pinned to 36ed6ad6665661a18f83394d561fa75c68ccf4ac.
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: Reach a compiling or fork-tested strategy scaffold using the octant-v2-strategy-foundry-mix starter template, with all known compatibility issues resolved against [email protected].

Start repo: octant-v2-strategy-foundry-mix@ddd405c18bb0c765c0256ca952d4d9f4034cf3ec

Core target pin: octant-v2-core@36ed6ad6665661a18f83394d561fa75c68ccf4ac (tag 1.2.0-develop.15)

Files to edit:

  • src/strategies/yieldDonating/YieldDonatingStrategy.sol — add _symbol parameter to the BaseStrategy constructor call
  • src/strategies/yieldDonating/YieldDonatingStrategyFactory.sol — add _symbol parameter to factory call
  • src/test/yieldDonating/YieldDonatingSetup.sol — update the test constructor call to include _symbol
  • src/test/yieldDonating/YieldDonatingFunctionSignature.t.sol — update the encoded initialize() ABI signature to include _symbol
  • foundry.toml — add [lint] lint_on_build = false if running Forge ≥ 1.5

Files NOT to edit:

  • dependencies/octant-v2-core/* — do not modify anything inside the core submodule; treat it as read-only

Required setup:

  • A working local environment from Local Development Quickstart
  • Foundry installed (forge --version)
  • The starter cloned at the pinned commit: git checkout ddd405c18bb0c765c0256ca952d4d9f4034cf3ec

Verification commands:

forge build
forge test

Do not:

  • Assume the starter's default branch is interchangeable with the pinned snapshot
  • Edit files inside dependencies/octant-v2-core/*
  • Skip the compatibility fixes before running forge build

(See also: Agent Anti-Patterns)

The octant-v2-strategy-foundry-mix repository provides a Foundry scaffold for building custom Yield Donating Strategy contracts. It is a convenience layer on top of octant-v2-core — use it when you want a narrower starting point than the full core repo.

Source-of-truth rule​

Use this order when the starter repo and the rest of the docs appear to disagree:

  1. [email protected] for contract architecture, signatures, and behavior,
  2. the starter repository you actually cloned for its local scripts, folder layout, and bundled files,
  3. this page for deciding whether to use the starter and what assumptions are safe.

In other words, a starter repo is a convenience layer. It is not automatically the canonical reference for the whole Octant surface.

When to use the strategy starter​

If you need to...Start withWhy
build a custom Yield Donating Strategy contractoctant-v2-strategy-foundry-mixit gives you a narrower Solidity scaffold than the full core repo
inspect protocol contracts, factories, or shared architecture directlyoctant-v2-coreit is the reference implementation layer

Strategy contract starter (Foundry)​

A Foundry project pre-wired to octant-v2-core for building custom Yield Donating Strategy contracts.

Source: golemfoundation/octant-v2-strategy-foundry-mix Docs target snapshot: octant-v2-strategy-foundry-mix@ddd405c18bb0c765c0256ca952d4d9f4034cf3ec reconciled to [email protected] Best for: custom YDS work when a pre-built factory flow does not already fit your use case Not a guarantee of: perfect out-of-the-box compatibility with the pinned core release if you clone a different starter revision

Use this when you need a yield source that is not already covered by one of the pre-built factory flows in core.

For a complete walkthrough from clone to a working strategy example, see the Hello World Strategy tutorial.

Fix required before forge build

These strategy-template tutorials now target octant-v2-strategy-foundry-mix@ddd405c18bb0c765c0256ca952d4d9f4034cf3ec together with [email protected]. Do not assume the starter repo's default branch is interchangeable with that audited snapshot.

At this tested starter revision, the scaffold still targets an earlier version of BaseStrategy and ITokenizedStrategy.initialize(). For [email protected], both require an additional _symbol parameter.

This affects four files: the strategy contract, the factory, and two test files. Before proceeding, apply the full reconciliation described in the Hello World Strategy — Compatibility note.

After the _symbol compatibility fixes, update any starter-template YDS tests that assert first deposits mint exactly 1:1. In 1.2.0-develop.15, the first empty-strategy deposit locks 1_000 shares at address(0xdead), so the user receives assets - 1000 shares.

Forge ≥ 1.5 lint-on-build note: If forge build still fails after the four fixes above with errors about unresolved src/... imports inside the core submodule, 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 — add as a top-level section in foundry.toml
[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.

Reproducibility notes for the audited starter snapshot​

Keep these local-state details in mind while you work:

  • yarn generates a local yarn.lock because this audited starter snapshot does not commit one. The starter repo gitignores that file, so it usually will not appear in git status.
  • The docs then ask you to manually re-pin dependencies/octant-v2-core to 36ed6ad..., so a modified submodule is expected in git status after bootstrap.
  • Do not run forge install for this starter snapshot. Soldeer populates the Solidity dependencies, and git submodule update --init --recursive populates the only Git submodule.
  • If you rerun git submodule update --init --recursive, it will reset that manual pin back to the starter repo's recorded revision. Re-apply the manual pin after any 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.
  • The helper described in Workflow Manifests can re-pin the submodule and reconcile the optional foundry.lock submodule entry to the docs target, but the working tree still remains locally modified relative to the audited starter snapshot.
Known issue — forge soldeer install panic on Forge 1.5.x on macOS

If forge soldeer install panics with Attempted to create a NULL object, stop and classify the failure as tooling. Missing imports after that panic still belong to the setup layer. Do not treat them as proof that the _symbol compatibility fixes or your strategy code are wrong.

When to choose this starter instead of a pre-built factory​

Choose the Foundry starter when:

  • your yield source is not already covered by a pre-built factory,
  • you need custom integration logic,
  • you need protocol-specific reporting, limits, or emergency handling,
  • you want full control over the Solidity implementation.

Quick start outcome​

Goal: reach a compiling or fork-tested strategy scaffold.

Use the environment and compatibility steps from Local Development Quickstart, then continue into Hello World Strategy.

If you want the machine-readable command list, stop conditions, and expected git-status snapshots for that bootstrap, use the companion manifest described in Workflow Manifests.

Expected output: a working strategy scaffold that matches the assumptions of the tutorial you are following.

How the starter relates to [email protected]​

The starter repo and the core repo serve different purposes:

  • octant-v2-strategy-foundry-mix is a Solidity starter for writing custom strategy contracts,
  • octant-v2-core (golemfoundation/octant-v2-core) is the reference implementation layer that defines the actual contract architecture, base contracts, and factory contracts. These docs are anchored to the pinned commit [email protected].

If you are unsure which layer should be your source of truth, use this rule:

  • for contract behavior and architecture, trust [email protected],
  • for local scaffold scripts and project layout, trust the starter repo,
  • if the starter and the pinned core source disagree, treat that as a version mismatch that must be resolved explicitly.

Retrieval cues​

If you are using an LLM or internal search to navigate the docs, this page answers questions like:

  • Which starter repo should I clone first?
  • When should I use the strategy Foundry mix instead of the core repo?
  • Can I trust the starter template as canonical?

Next steps​