Igra Labs issued upgrade instructions to Orchestra node operators and attesters on June 23, directing them to begin moving mainnet deployments from v2.3 to v3.0 ahead of Toccata. Igra's runbook splits the upgrade into two phases around activation: backend services move now, while worker services remain on v2.3 until the network accepts the post-fork transaction path. (Igra Labs on X, Igra upgrade guide)
Igra's post says the activation is tied to a fixed Kaspa DAA score and is estimated around June 30. The warning is practical rather than promotional: operators who leave the backend on the old line at activation risk falling off chain and stalling, while operators who move the worker side too early risk producing transactions in a format mainnet is not ready to accept. (Igra Labs on X, Igra upgrade guide)
What Igra is and why this matters
Igra documentation describes the network as a high-performance blockchain built on Kaspa BlockDAG proof of work with full EVM compatibility. Its mainnet infrastructure is operated through Igra Orchestra, a deployment stack that includes kaspad, reth, RPC providers, kaswallet workers, ATAN archive handling, health checks and node-specific environment configuration. (Igra Network documentation, Igra Orchestra repo)
That makes the Toccata upgrade a stack-level operation, not a simple binary bump. Orchestra has backend components that must understand the new rules before activation, and worker components that must keep using the pre-activation transaction path until the cutover has actually happened. Igra's runbook is built around keeping those two requirements separate. (Igra upgrade guide, mainnet version pins)
What Toccata means for Igra specifically
The Igra-specific change centers on the lane/subnetwork path. Igra's mainnet lane value is 97b10000, exposed in Orchestra as IGRA_LANE_ID. That value is passed to kaspad as --igra-lane-id during the backend upgrade and later reaches kaswallet as --subnetwork-id after the worker side moves to v3.0. (environment reference, Docker Compose file)
Igra keeps TX_ID_PREFIX=97b1 alongside the lane value. The prefix remains the legacy transaction prefix and the ATAN import namespace, while IGRA_LANE_ID=97b10000 is the post-KIP-21 lane namespace. Docker Compose now refuses to render without both values, and the kaspad entrypoint has runtime guards for empty variables. (environment reference, Docker Compose file)
That separation already produced a real fix. In commit 648fe99, Igra changed the ATAN import URL to use TX_ID_PREFIX rather than the shared lane ID, because mainnet ATAN data is published under /mainnet/97b1/index.pb. Using the lane value would have pointed the node at the wrong CDN object. (commit 648fe99)
Phase one - backend only
Phase one covers kaspad and reth, the backend components. Operators pull the latest Orchestra code, run scripts/upgrade-mainnet-v2.3-to-v3.0.sh, validate the Compose configuration and restart only the backend profile. The script edits .env, writes a timestamped backup, inserts the lane value, checks mainnet identity through NETWORK=mainnet and IGRA_CHAIN_ID=38833, and syncs image pins from versions.mainnet.env. It does not touch Docker volumes. (upgrade script, mainnet deployment guide)
The first backend start uses KASPAD_NONINTERACTIVE=true so kaspad can handle a one-time database metadata prompt inside Docker without blocking. After kaspad gets past that prompt and resumes from the previous chain height, the guide tells operators to recreate kaspad again without the temporary flag. (Igra upgrade guide, kaspad DB troubleshooting)
Worker services stay pinned to v2.3 throughout phase one. Igra's version file reflects the split explicitly: KASPAD_VERSION and RETH_VERSION read 3.0, while KASWALLET_VERSION and RPC_PROVIDER_VERSION remain at 2.3. Operators should see backend services on v3.0 and worker services still on v2.3 after the first phase is complete. (mainnet version pins, Igra upgrade guide)
One operational detail in the runbook involves file ownership. A running v2.3 deployment can leave config/traefik/ owned by root, preventing Git from writing the newly tracked dynamic.yml file during the pull. Igra documented the ownership fix in the upgrade guide and added it to the troubleshooting table after commit f241c11. (Igra upgrade guide, commit f241c11)
Phase two - workers after activation
Phase two begins only after Toccata activates. At that point, operators set RPC_PROVIDER_VERSION=3.0 and KASWALLET_VERSION=3.0, validate Compose again and recreate the same worker profile they already run. Once the worker side is on v3.0, kaswallet receives --subnetwork-id=$IGRA_LANE_ID and begins emitting the post-Toccata transaction form on Igra's lane. (Igra upgrade guide, Docker Compose file)
Igra Labs added a specific warning for attesters: pause attestation activity before starting phase two. The worker upgrade changes the transaction-producing side of the stack, so live attestation activity carries extra cutover risk beyond the image update itself. (Igra Labs on X, Igra upgrade guide)
A June commit also ensures v2.3 workers cannot accidentally receive the post-Toccata --subnetwork-id flag. Commit 6adf05f gates that argument by KASWALLET_VERSION, passing it only when the kaswallet major version is v3 or newer. That prevents a v2.3 kaswallet binary from receiving an argument it does not understand. (commit 6adf05f)
Why the split matters
The split addresses two different failure modes. A backend that remains on v2.3 past activation can fall off the network because it lacks the required post-fork path. A worker stack moved to v3.0 before activation can attempt to construct transactions in a format the network has not yet accepted. Igra avoids both by requiring backend readiness before activation and holding the worker cutover until after.
The public Orchestra commit history shows the runbook being tightened around that sequence. Commit 6ad7fb5 added the mainnet v2.3 to v3.0 runbook and .env updater, 36d4fbb added a TL;DR operator path, 1b12f83 exposed the page in the documentation sidebar, and c96db2b reframed the page as "Toccata Upgrade - Part One" so operators see the pre-activation and post-activation stages before changing containers. (commit 6ad7fb5, commit 36d4fbb, commit 1b12f83, commit c96db2b)
Operators should follow Igra's full runbook for the actual commands, validation steps and troubleshooting. The main takeaway from the June 23 notice is the order: backend to v3.0 now, workers after Toccata, with lane values in place before both.