full package history

[chrisgitiota]

Description of change

product_common::PackageRegistry now supports the full package version history. It uses a Move.history.json file to import the version history and known environments (as being previously done with Move.lock files).

The Move.history.json file

• should be located in the same directory as the Move.lock file
• contains all data that is provided by the PackageRegistry
• should be added to the git repository of the product that uses the PackageRegistry
• will be integrated into build rust binaries at build time (using include_str!()) - like the previously used Move.lock file had been integrated in the build
• should not be used to store the history of localnet networks, as this would mass up the file. For this purpose the MoveHistoryManager described below, offers a aliases_to_ignore list which is set to localnet per default.

For example the Move.history.json for the recent (not latest) Identity package would look like this:

{
  "aliases": {
    "devnet": "e678123a",
    "testnet": "2304aa97",
    "mainnet": "6364aad5"
  },
  "envs": {
    "6364aad5": ["0x84cf5d12de2f9731a89bb519bc0c982a941b319a33abefdd5ed2054ad931de08"],
    "e678123a": [
      "0xe6fa03d273131066036f1d2d4c3d919b9abbca93910769f26a924c7a01811103",
      "0x6a976d3da90db5d27f8a0c13b3268a37e582b455cfc7bf72d6461f6e8f668823"
    ],
    "2304aa97": [
      "0x222741bbdff74b42df48a7b4733185e9b24becb8ccfbafe8eac864ab4e4cc555",
      "0x3403da7ec4cd2ff9bdf6f34c0b8df5a2bd62c798089feb0d2ebf1c2e953296dc"
    ]
  }
}

Product build.rs scripts

The Move.history.json for a product can be created manually or automatically using the MoveHistoryManager in buils.rs scripts .

See the docs of the MoveHistoryManager for further details.

An example for a build.rs script using the MoveHistoryManager to manage its Move.history.json file can be found in the Notarization - Full package history PR.

Links to any relevant issues

Will fix: NOTARIZATION_PACKAGE_REGISTRY: Support full package address version history #71

[UMR1352]

Mostly nitpicks, feel free to disregard anything you don't agree with

[itsyaasir]

Issue 1

The build script requires env tables in Move.lock, but fresh Move projects don't generate these until after first deployment.

Root Cause:

• MoveHistoryManager parser expects [env.{network}] sections with original-published-id and latest-published-id
• New/unpublished Move packages don't have these entries yet
• Build fails before you can even publish the contract

Impact:
This creates a problem where you can't build your client until you've published your contract at least once on each target network.

Typical Scenario:

• Create new Move package → Move.lock has no env tables
• Try to build Rust client → Build fails
• Can only proceed after publishing contract to generate the env entries

Solution needed: The parser should either:

• Accept empty/missing env tables gracefully for new projects.

[itsyaasir]

Issue 2

Custom aliases are not being written to Move.history.json - the aliases field remains empty {} even after deployment with custom aliases defined.

Current State:

{
    "aliases": {}, # Empty despite having an alias
    "envs": {
      "ead649fb": ["0x3cd00d411d6a74d833d7f690025ebd4ce3c2f4934afd29ab141fe474ee335282"]
    }
}

Expected Behavior:
Custom aliases should be populated in the aliases object, mapping alias names to their chain-ids:

{
   "aliases": {
     "my-custom-network": "ead649fb"
   },
   "envs": { ... }
}

[itsyaasir]

Issue 3

When an environment is deleted from Move.lock and the contract is redeployed, Move.history.json retains old package IDs that no longer exist in Move.lock, creating a mismatch between the two files.

Reproduction:

• Initial state - testnet has deployments in both files:
  • Move.lock: original-published-id = "0xold1", latest-published-id = "0xold2"
  • Move.history.json: "2304aa97": ["0xold1", "0xold2"]
• Delete [env.testnet] section from Move.lock
• Redeploy contract to testnet (fresh publish)
• Result:
  • Move.lock: original-published-id = "0xnew3", latest-published-id = "0xnew3"
  • Move.history.json: "2304aa97": ["0xold1", "0xold2", "0xnew3"]

Impact:

• Stale history - History contains 0xold1 and 0xold2 but
  lock file only knows about 0xnew3
• No way to validate which historical IDs are still valid
• History accumulates IDs that are disconnected from current
  deployment state
• Lock file is no longer the source of truth for what's actually
  deployed

Root Cause:
MoveHistoryManager appends to history without checking if the lock file's package IDs are a subset of history's IDs - it never removes stale entries when lock file is reset.

The real question is how should we handle this ? do we want the history and the lock file to be always be in sync ? Making the lock file to be the absolute source of truth ? or the history will be like audit trail where it has "permanent" record of the deployment history.

[itsyaasir]

Issue 4

Aliases are inconsistently written to Move.history.json - some aliases appear while others don't, and aliases appear at unexpected times unrelated to their actual deployment.

Current State:

{
  "aliases": {
    "localnet": "ead649fb"  // ← Appeared after testnet deployment (???)
  },
  "envs": {
    "ead649fb": ["0x3cd..."],
    "2304aa97": ["0xabc..."]  // ← testnet chain-id, but no alias
  }
}

Reproduction:

• Deploy to localnet - env values is reflected without the alias name

• Deploy to testnet → aliases localnet appears but testnet doesn't appear on the alias but env values are there

• Deploy to devenet → Same behavior as localnet

• Run cargo build multiple times → No change

  Expected Behavior:
  After each deployment, the corresponding alias should be written:

{
  "aliases": {
    "localnet": "ead649fb",
    "testnet": "2304aa97",
    "devnet": "e678123a"
  },
  "envs": {
    "ead649fb": ["0x..."],
    "2304aa97": ["0x..."],
    "e678123a": ["0x..."]
  }
}