Adding a State

DigiFIR is designed so that a new State joins by configuration, not by redesign. The State's police become a new member organisation with their own certificate authority, two peers and their own private data collections. The channel's governance policies are rewritten to include them, and the backend learns their gateway. The procedure was rehearsed on the development network with a third state, State C (PoliceStateCMSP, state code MH, collection tag C).

What the new State brings

• Its own Fabric CA (identity CA and TLS CA), issuing every certificate of the organisation.
• Two peers, each with its own CouchDB, and its own chaincode servers.
• Its private data collections stateC_private (in fir-registry, evidence-custody and judicial-actions) and stateC_lab (in evidence-custody), shared with the judiciary, and with the laboratories for the lab collection.
• Its registrar, gateway identity and reference data: districts, stations, station areas.
• In the pilot, its own HSM partition, and its own HSM token in the backend.

Existing collections and records do not change. Fabric does not allow a collection to be removed or its retention changed, and the design does not need it.

Who does what

Step	Who	Signatures needed
1. CA, crypto, peers, CouchDB	The new State	None
2. Organisation definition	The new State	None
3. Channel update adding the organisation	Any member's administrator builds it	The judiciary's administrator and two of the other three members' administrators. The same update rewrites the governance policies for five members.
4. Peers join the channel	The new State	None
5. Anchor peer	The new State	The State's own administrator
6. New chaincode definitions, sequence plus one	Every organisation approves, one commits	The judiciary and two of the other four; in the pilot, the commit waits until all five have approved
7. The State in the contracts	MSP administrators, then the State's registrar	Endorsements as each function requires
8. Backend settings	The backend's operator	None

Steps

1. Start the State's CA, enrol its peers, administrators and gateway, and start its two peers and CouchDB. On the development network: ./scripts/network.sh addOrg police-c.

2. Write the organisation definition with configtxgen -printOrg.

3. Build the channel configuration update that adds the organisation and rewrites the Admins, LifecycleEndorsement and Endorsement policies for five members (scripts/ops/config-update.sh governance). Review the decoded write set, collect the administrators' signatures, and submit it.

   NOTE

   In the drill, an update with only two signatures was refused, as the governance rule requires.

4. Join the State's peers to firnational.

5. Set the State's anchor peer.

6. Give each of the four chaincodes a new definition with the same version and the next sequence. Add PoliceStateCMSP.peer to every OR and OutOf of its endorsement policy, and add the new collections, generated from State A's. Every organisation approves, and one commits.

7. Register the State in the contracts, in order:

   • identity-registry.AddInstitution, submitted by a member's MSP administrator and endorsed by every member;
   • fir-registry.OnboardState and evidence-custody.OnboardState;
   • BootstrapRegistrar for the State's first registrar;
   • the State's gateway key, then its districts and stations, registered by its registrar.

   On the development network, ./scripts/network.sh onboardState police-c MH '<name>' <district> '<name>' does all of this and reads back the anchors' key-level policies from the committed blocks.

8. Add the State's gateway and peers to the backend's FABRIC_GATEWAYS (and PROJECTOR_PEERS), with its own HSM token, PIN and document key in the pilot. The backend refuses a pilot configuration in which the State shares a token or PIN with another institution. FABRIC_GENESIS_HASH does not change, because a joining State adds configuration blocks, never a new block 0; the State's operators check the value once against their own peer.

Verify the onboarding

• The channel configuration lists five application organisations and the State's anchor peer.
• Both of the State's peers are at the same height as the others, and every chaincode is at its new sequence with the State's collections, naming PoliceStateCMSP in each policy.
• GetInstitution PoliceStateCMSP answers, the gateway key is ACTIVE, and a station reads back.
• A State C officer's private record is readable on both State C peers and by the judiciary, refused to State A, stored only in State C's and the judiciary's CouchDB, and its hash can be checked by the laboratories without reading it.

The drill

The final drill on 1 November 2026 ran every operations runbook on the development network, including State C's onboarding, on the HSM profile. It took 31 minutes and ended with 55 smoke checks passing on five organisations and eight peers.

Beyond the police of a State

The same mechanism, AddInstitution after a channel update, also admits other institutions, such as another court system or laboratory organisation. Prosecution and prisons as ledger members are outside the current pilot.

Sources: digifir-network docs/OPERATIONS.md ("Onboarding a new state", "Verification log"), docs/KUBERNETES.md ("Joining a new institution"), README.md; digifir-chaincode docs/SPEC.md section 6.3; digifir-backend docs/architecture/DECISIONS.md ADR-04, docs/PLAN.md section 1.