Migration from 1.1.18 -> 1.2.0rc2

[kentbull]

This is the collection point describing all necessary steps to perform a migration from the v1.1.18 version of KERIpy to v1.2.0rc2+.

Relevant issue list

• Migration bug on qnfs database key lookup - ERR: invalid literal for int() with base 16: b'EA59RST48MLqNoh_jNxHysEXFL4PeQlj2mII0TVEdz64' #863

Upgrade Path

Witnesses steps:

1. Shut down v1.1.x witnesses.
2. Upgrade the KERIpy library to 1.2.0rc2.
3. Run kli migrate run --name {witness keystore name}.
4. Start your witnesses back up.

Controller steps:

1. shut down the v1.1.x controllers.
2. Upgrade the KERIpy library to 1.2.0rc2.
3. Run kli migrate run --name {controller keystore name}.
4. Start your controller back up.

Relevant PRs

• fix: update smids and rmids for group lead on new event #858
• fix: update smids and rmids on rotate #857
• adds escrow clearing #864

Witness Migration

• One liner for demo witness migration:

  witnesses=(wan wil wes wit wub wyz); printf '%s\n' "${witnesses[@]}" | xargs -I {} kli migrate run --name {}

Code Changes

• keri.core.coring.Serials -> keri.core.coring.Kinds
• keri.core.coring.Salter -> keri.core.signing.Salter
• keri.app.delegating.Sealer -> keri.app.delegating.Anchorer
• (older) keri.app.delegating.Boatswain -> keri.app.delegating.Anchorer

FAQ

• Will events generated by KERI 1.1.x be recognized by KERI 1.2.0rc2+?
  • Yes, none of the event structures have changed nor the CESR primitives. The CESR 2.0 count codes are only used in unit tests and are entirely complementary to CESR 1.0, so there's nothing to worry about from a CESR 1.0 perspective.
  • The KERIpy parser is being upgraded to understand both the mew CESR 2.0 count codes. It still maintains support for all CESR 1.0 primitives and count codes. So all KERI 1.1.x CESR data structures will be recognized by a KERI 1.2.0rc2+ witness or controller instance.
    • Only when the ecosystem switches to CESR 2.0 will a 1.1x witness or controller not be able to receive a CESR 2.0 stream unless it upgrades its parser, though we do not need to worry about that for this upgrade since CESR 2.0 is not yet fully activated.

[kentbull]

We need to add clearing the following escrows (thanks Kevin) to the migration workflow:

            hby.db.gpwe.trim()
            hby.db.gdee.trim()
            hby.db.dpwe.trim()
            hby.db.gpse.trim()
            hby.db.epse.trim()
            hby.db.dune.trim()
            hby.db.qnfs.trim()

[kentbull]

It turns out the migration in keri.app.cli.commands.migrate.py is not needed for the migration from 1.1.18 to 1.2.0rc2 and is being removed in #869.

[kentbull]

The delegation ceremony changed between 1.1.x and 1.2.x in a non-backwards compatible way. Details to follow.

[kentbull]

The details were that the delegation ceremony significantly changed from the old to the new ceremony.

Old KERIpy 1.1.x delegation ceremony

1. DELEGATE creates delegated inception (dip) event and immediately sends it to DELEGATOR PRIOR to getting witness receipts from the DELEGATE WITNESSES, which occurs at the end of the process.
2. DELEGATOR anchors the delegated inception (dip) event in an interaction event (ixn), the approval of the delegation
3. DELEGATOR gets receipts from the DELEGATOR WITNESSES of this approval and
4. DELEGATOR sends both the interaction event and its receipts back to the DELEGATE.
5. DELEGATE sends the dip, the ixn, and the ixn receipts to the DELEGATE WITNESSES after which those witnesses then receipt the DELEGATE's dip event.
6. Delegation is complete.

Witnesses with the OLD delegation ceremony will not accept the dip event to witness it until after they receive the delegation approval ixn and its receipts, meaning KERIpy 1.1.x witnesses WILL NOT WORK with KERIpy 1.2.x delegation since they will wait forever for the delegation approval ixn and its receipts yet those are not sent by the delegate in 1.2.x until after the delegate gets its dip receipts.

New KERIpy 1.2.x+ delegation ceremony

In KERIpy 1.2.0+ the

1. DELEGATE creates the dip event
2. DELEGATE receipts the dip immediately with the DELEGATE WITNESSES and
3. DELEGATE sends both the dip and its receipts to the DELEGATOR.
4. DELEGATOR anchors the dip in an approval exn,
5. DELEGATOR receipts the approval ixn with the DELEGATOR WITNESSES and
6. DELEGATOR sends the approval ixn and its receipts back to the delegate.
7. Delegation is complete.