feat(config): begin and end a registry migration with update-config, and read a Config that grew

[rssh]

Spec rev 5.6 (ft-bifrost-bridge #56, [CFG-10]) revises the SPO registry without redeploying the bridge. One governance Update moves Config #9 to the new registry, moves #8 to its ban list, and appends #13 previous_spos_registry_policy_id, the registry pools are crossing from. heimdall carries registrations across by itself (lantr-io/heimdall#114). This PR is binocular's part of that Update, and it makes sure binocular keeps working once the Config has fourteen fields.

update-config

• --migrate-registry-to <policy> sets ci: migrate workflow from mill to sbt #9 to the new registry and feat(peg-out): complete peg-out flow + witness/reorg fixes + optional peg-out config #13 to whatever ci: migrate workflow from mill to sbt #9 held, in one edit. feat(peg-out): complete peg-out flow + witness/reorg fixes + optional peg-out config #13 is read from the datum, not typed: a feat(peg-out): complete peg-out flow + witness/reorg fixes + optional peg-out config #13 that isn't the old ci: migrate workflow from mill to sbt #9 would point every node at a list with nothing to migrate.
  • It requires --spo-bans-policy in the same Update. The three fault verifiers are compiled from the registry hash, and the ban policy from theirs, so the ban list has to move with the registry.
  • It refuses if a migration is already in progress.
• --end-registry-migration empties feat(peg-out): complete peg-out flow + witness/reorg fixes + optional peg-out config #13 once every pool has crossed. It never removes the field ([CFG-5] only appends).

The rollout's step c3 is therefore:

update-config --migrate-registry-to <new registry policy> --spo-bans-policy <new ban policy>
# … pools cross …
update-config --end-registry-migration

Reading a Config that grew

update-config used to refuse any Config longer than the rev 5.5 layout, because re-encoding it would drop the appended field. Refusing was safe, but it made #13 impossible to write, and impossible to write any other field once #13 exists. DeployedConfig now carries appended fields verbatim, and update-config, the proof service, the sweep setup and the PoR sweeper all decode through it.

ConfigDatum is deliberately unchanged, still the thirteen-field mirror. TreasuryMovementValidator decodes it on chain, so a fourteenth field would move that validator's pinned hash. That would mean a new TM script for a change that has nothing to do with it.

The deployed TM validator and #13

This was the real risk: the TM validator is already deployed, and it reads the Config. New tests evaluate the pinned blueprint program, the exact UPLC on chain, on both the confirm and mint paths, against a Config with #13 appended, once mid-migration and once ended. It accepts all four. So the migration's Update does not stop treasury movements on a live bridge.

Which contracts a bridge runs: bridge.contracts

binocular now carries two contracts releases: rev 5.5 (ft main, what the preprod bridge runs) and rev 5.6 (ft 096f76c, what heimdall embeds). bridge.contracts in the config file says which one the bridge was deployed with. It defaults to rev5.5, so existing config files keep working, and the preprod config now states it explicitly.

It's a property of the bridge, fixed at genesis, and a registry revision does not change it. The revision replaces the registry and the ban list, which heimdall deploys. The Config, peg and TM scripts that binocular spends stay the ones the bridge was deployed with.

The vendored blueprint carries its release, and the release decides:

• spos_registry: rev 5.6 adds the Config NFT policy as a fourth parameter.
• spo_bans: the first parameter is the registry policy in rev 5.5, and the Config NFT policy in rev 5.6.
• the Config genesis writes: 13 fields, or 14 with feat(peg-out): complete peg-out flow + witness/reorg fixes + optional peg-out config #13 empty. rev 5.6's config.ak genesis mint casts all 14.

The rev 5.6 policy ids are pinned against heimdall's independent Rust derivation from the same bytes, the same cross-check that already locks rev 5.5.

After a revision: deploy-script-refs and register-bridge-creds

Both rebuilt the registry and ban list from #12 and refused unless they matched #9 and #8, so after a revision both would have failed on the live bridge. They now classify the Config:

• The treasury still matches but the registry has moved: that's a revision. They skip the SPO half with a message, because heimdall publishes those reference scripts and registers that credential.
• A wrong one-shot still fails, on the treasury.

bridge.plutus-json

It used to default to ../../FluidTokens/ft-bifrost-bridge/onchain/plutus.json and fall back to the packaged blueprint silently when that file was absent. The contracts a command built with therefore depended on whether, and on which branch, an ft checkout sat next to the working directory. On a machine whose checkout is on the rev 5.6 branch, a genesis would have deployed rev 5.6 without a word. It now defaults to empty, meaning the packaged blueprint of contracts, and a path that can't be read is refused.

docs/operator-guide.md

binocular's first guide for the people who run a bridge. It covers:

• what binocular does for one;
• the bridge section (contracts above all);
• genesis in order across heimdall and binocular;
• the watchtower;
• changing the Config, including the registry migration;
• what the common refusals mean.

The README's command table, which listed commands that no longer exist, now points to it.

Not covered here

• Whether the deployed config.ak accepts an Update that appends a field. The spec says config.ak accepts any datum shape, but that has to be seen on chain. The preprod rehearsal (a separate test bridge migrated end to end before release) is where it will be.
• A rev 5.6 genesis on chain. It is pinned offline against heimdall's derivation, but it hasn't been deployed yet.

Tests

All 724 pass under sbt testFull after the full cache reset. Plain sbt test in sbt 2 is incremental: it reported 125 and 621 on earlier runs of this branch, which is exactly the partial-run trap binocular's CLAUDE.md warns about. The freshness check now passes whichever of the two vendored releases the neighbouring ft checkout is on.