Simplify staking contract migration for node operators

[awmacpherson]

Summary

Bee should make it straightforward for node operators to move stake from an obsolete staking contract into the current deployment using only a new Bee release. Operators should not need to run an old Bee version (as suggested in the v2.3.0 migration guide, restart Bee specifically to perform the migration, or find and supply historical contract addresses and ABIs.

These UX improvements could be delivered in three progressively more automated tiers:

1. An explicitly triggered API operation in the latest Bee version that performs the legacy withdrawal and optionally deposits the recovered stake into the current staking contract.
2. An opt-in startup flag or configuration value that asks the latest Bee version to perform the same migration during daemon startup.
3. A scheduled migration coordinated around a chain-specific fork block known to Bee in advance.

Motivation

When the staking contract is replaced, stake may remain associated with node accounts in the old deployment. Bee's normal configuration follows the current deployment, so recovering that stake can require historical release knowledge and manual contract interaction. This is especially awkward for operators using automated Docker deployments, where the expected workflow is to pull the latest Bee image and manage the node through configuration and its HTTP API.

I believe the known operational complexity of executing stake migrations may be having a chilling effect on rolling out chain protocol upgrades that require a new stake registry. If that's true, alleviating this complexity could significantly improve the agility of the protocol improvement process.

The suggested operator experience is:

• upgrade to the latest Bee release;
• explicitly approve migration through the API or configuration;
• let Bee identify the relevant legacy deployment, submit the required transactions, and report progress or partial failure;
• continue operating against the current staking deployment.

The operation must remain triggered by explicit opt-in because it moves tokens and submits on-chain transactions.

Implementation

Bee currently ingests smart contract deployment configuration via the go-storage-incentives-abi package, which in turn is generated as part of the release CI process of the storage-incentives repo (codegen script here). The lowest footprint way to get legacy staking contract configurations into bee is therefore to extend the codegen pipeline so that go-storage-incentives-abi preserves versioned historical staking deployments instead of exposing only the latest generated staking values.

Each generated record should include an externally assigned deployment ID, chain ID, address, deployment block, and enough of the staking ABI to execute a migration. If scheduled migration (tier 3) is desired, the complete ABI must be included. The existing storage-incentives release tag is a suitable deployment ID; several release IDs may map to the same contract address.

Bee can then select supported current and legacy deployment records in its chain configuration and construct allowlisted staking clients for them. API and configuration inputs should refer only to generated deployment IDs. An operator should never need to provide a contract address or ABI.

The three UX tiers are:

1. Manual API migration. Add an endpoint such as POST /stake/migrations/{deployment_id}. One request should inspect the node's stake in the selected legacy deployment and call its paused-contract migration operation. Optionally, depositing the recovered amount into the current deployment could be bundled into the same call. The response and status API must distinguish full success from cases where withdrawal succeeded but approval or redeposit did not.
2. Opt-in startup migration. Add a flag or configuration value identifying an approved generated deployment ID. During startup, Bee performs or resumes the migration before enabling staking-dependent operation. This needs persistent progress and transaction tracking so restarts are safe.
3. Scheduled migration block. Publish the old deployment, new deployment, and chain-specific migration block before the upgrade. Bee continues to treat the old contracts as fully operational before that block, switches to the new deployment at the block, and begins migration only for operators who approved it. The administrator's pause of the old contract must be coordinated with the same transition.

The first tier can be implemented and reviewed independently. The later tiers can reuse the same generated deployment catalog and migration orchestration.

Considerations

• Retaining full historical staking ABIs increases the generated ABI module size.
• If the maintainer ever wishes to remove legacy ABIs from the codebase, there should be an explicit social contract as to how long legacy ABIs will be supported.
• Supporting multiple legacy deployments increases configuration and test coverage in Bee (though this can be mitigated by ensuring that migration ABIs are stable).
• Withdrawal, token approval, and redeposit are separate transactions. If bee is to bundle these together into a single user action, it must be able to expose and recover from partial completion.
• Startup automation requires durable state and careful idempotency to avoid duplicate transactions after a crash.
• A coordinated fork block introduces chain-head and reorganization handling and requires release coordination between contract administrators, Bee maintainers, and node operators.

AI Disclosure

• This issue contains suggestions and text generated by an LLM.
• I have reviewed the AI generated content thoroughly and made adjustments for clarity.
• I possess the technical expertise to responsibly review the AI generated content mentioned in this issue.

[aloknerurkar]

@awmacpherson I think building this functionality into bee increases complexity. Better would be to create a tool which can do this externally. Wdyt?

[awmacpherson]

Certainly, adding this feature increases complexity, though at tier 1 it seems pretty minor (Sol estimates ~500 LOC) and low-maintenance compared to other features that could easily have been a separate tool but have nonetheless been added to bee (e.g. all stake registry endpoints could be a separate tool). I'm happy to write it, but aware that review is probably the bottleneck here.

The benefit of adding it to bee as opposed to making a new tool is distribution: we can be certain that all node operators have it, and hence gain confidence that stake migrations go smoothly, which is the main motivation of this proposal. Asking operators to install a special migrator tool reintroduces more steps into the upgrade process.