@twin.org/move-to-json 0.0.3-next.1 → 0.0.3-next.10

package/README.md

@@ -1,387 +1,21 @@
 # TWIN Move to JSON
 
-Tool to convert Move source files to JSON with network-specific deployment support.
-
-## Prerequisites
-
-### IOTA CLI Installation
-
-Before using this tool, you need to install the IOTA CLI. The simplest way is using Homebrew:
-
-```bash
-# Install IOTA CLI using Homebrew (macOS/Linux/WSL)
-brew install iotaledger/tap/iota
-```
-
-**Alternative installation methods:**
-
-For other platforms or installation from source, see the [official IOTA installation guide](https://docs.iota.org/developer/getting-started/install-iota).
-
-**Verify installation:**
-
-```bash
-iota --version
-```
+This app provides a command line workflow for compiling Move contracts and producing deployment-ready JSON for IOTA networks. It is intended for development teams that want predictable build and deployment inputs across test and production environments.
 
 ## Installation
 
 ```shell
-npm install -g @twin.org/move-to-json
-```
-
-## Quick Start
-
-```bash
-# Build contracts for mainnet using environment variables (recommended)
-npx move-to-json build "src/**/*.move" --load-env configs/mainnet.env --output smart-contract-deployments.json
-
-# Deploy to mainnet using environment variables (recommended)
-npx move-to-json deploy --load-env configs/mainnet.env --contracts smart-contract-deployments.json
-```
-
-## Environment Setup for Production Deployments
-
-### Required Environment Variables
-
-For production deployments, you need to set up environment variables containing your deployment credentials. The tool uses network-specific configuration files located in the `configs/` directory.
-
-#### 1. Create Environment Files
-
-Copy the environment templates for each network you plan to use:
-
-```bash
-# Copy environment templates for each network
-cp configs/testnet.env.example configs/testnet.env
-cp configs/devnet.env.example configs/devnet.env
-cp configs/mainnet.env.example configs/mainnet.env
-```
-
-**Note:** Only copy the environment files for the networks you actually plan to deploy to. For development, you typically only need `testnet.env` and `devnet.env`.
-
-#### 2. Generate Deployment Mnemonics
-
-Use the wallet CLI to generate secure mnemonics and then manually update the appropriate network configuration files with the generated mnemonic.
-
-### Environment Variable Reference
-
-Each network has its own configuration file in the `configs/` directory with the required deployment mnemonic:
-
-| Network | File                  | Required Variable   |
-| ------- | --------------------- | ------------------- |
-| Testnet | `configs/testnet.env` | `DEPLOYER_MNEMONIC` |
-| Devnet  | `configs/devnet.env`  | `DEPLOYER_MNEMONIC` |
-| Mainnet | `configs/mainnet.env` | `DEPLOYER_MNEMONIC` |
-
-### Security Best Practices
-
-#### Local Development
-
-- Store credentials in `configs/*.env` files (never commit to git - only commit `.example` files)
-- Use test mnemonics with faucet funds for testnet/devnet
-- Use dedicated deployment wallets separate from personal wallets
-
-#### CI/CD and Production
-
-- Store credentials in GitHub Secrets or your CI/CD secrets manager
-- Use hardware wallets or HSM for mainnet deployment keys
-- Implement approval workflows for mainnet deployments
-- Monitor wallet balances and deployment costs
-
-### Generating Credentials
-
-#### 1. Generate Mnemonic and Seed
-
-```bash
-# Generate a new 24-word mnemonic and save to wallet.env
-npx "@twin.org/wallet-cli" mnemonic --env wallet.env
-```
-
-#### 2. Generate Addresses from Seed
-
-```bash
-# Generate 5 addresses and save to address.env
-npx "@twin.org/wallet-cli" address --load-env wallet.env --seed '!SEED' --count 5 --env address.env
-```
-
-## Commands
-
-### build
-
-Compile Move contracts for a specific network:
-
-```bash
-# Using environment variables (recommended)
-npx move-to-json build "src/**/*.move" --load-env configs/<network>.env [--output <file>]
-
-# Using explicit network flag
-npx move-to-json build "src/**/*.move" --network <network> [--output <file>]
-
-# If installed globally
-move-to-json build "src/**/*.move" --load-env configs/<network>.env [--output <file>]
-```
-
-**Options:**
-
-- `--network <network>` - Target network (testnet/devnet/mainnet) **[Optional if using --load-env]**
-- `--load-env <file>` - Load environment variables from file (must contain NETWORK variable)
-- `--output <file>` - Output JSON file (default: smart-contract-deployments.json)
-
-**What it does:**
-
-1. Reads network from `--network` flag or `NETWORK` environment variable
-2. Validates environment variables for the target network
-3. Cleans build artifacts and Move.lock files
-4. Compiles contracts using unified Move.toml (same bytecode for all networks)
-5. Generates network-aware JSON with package IDs and base64 modules
-
-**Key Changes:**
-
-- **Unified Move.toml**: Uses single Move.toml file with `framework/testnet` for consistent builds
-- **Network-agnostic compilation**: Same bytecode works across all networks
-- **Environment-aware**: Network targeting handled by IOTA CLI environments, not Move.toml
-
-**Example:**
-
-```bash
-# Build for testnet using environment variables (recommended)
-npx move-to-json build "tests/fixtures/sources/**/*.move" --load-env configs/testnet.env --output tests/fixtures/smart-contract-deployments/smart-contract-deployments.json
-
-# Build for mainnet using environment variables (recommended)
-npx move-to-json build "src/contracts/**/*.move" --load-env configs/mainnet.env --output smart-contract-deployments.json
-
-# Alternative: using explicit network flag
-npx move-to-json build "tests/fixtures/sources/**/*.move" --network testnet --output tests/fixtures/smart-contract-deployments/smart-contract-deployments.json
-```
-
-### deploy
-
-Deploy compiled contracts to the specified network:
-
-```bash
-# Using environment variables (recommended)
-npx move-to-json deploy --load-env configs/<network>.env [--contracts <file>] [options]
-
-# Using explicit network flag
-npx move-to-json deploy --network <network> [--load-env configs/<network>.env] [options]
-
-# If installed globally
-move-to-json deploy --load-env configs/<network>.env [--contracts <file>] [options]
+npm install -D @twin.org/move-to-json
 ```
 
-**Options:**
+## Usage
 
-- `--network <network>` - Network identifier (testnet/devnet/mainnet) **[Optional if using --load-env]**
-- `--load-env <file>` - Load environment variables from file (must contain NETWORK variable)
-- `--contracts <file>` - Compiled modules JSON file (default: smart-contract-deployments.json)
-- `--dry-run` - Simulate deployment without executing
-- `--force` - Force redeployment of existing packages
+Usage of the CLI is shown in the examples [docs/usage.md](docs/usage.md)
 
-**What it does:**
+## Reference
 
-1. Switches IOTA CLI to target network environment
-2. Loads environment variables from the file specified via `--load-env` flag
-3. Validates deployment credentials are available
-4. Checks wallet balance against gas requirements
-5. Loads compiled contracts from JSON
-6. Deploys using IOTA CLI with active network environment
-7. Extracts and saves both Package ID and UpgradeCap ID
-8. Updates JSON with deployed package information
+Detailed reference documentation for the API can be found in [docs/reference/index.md](docs/reference/index.md)
 
-**Key Changes:**
+## Changelog
 
-- **Environment switching**: Automatically switches IOTA CLI to target network
-- **Network targeting**: Uses IOTA CLI environments instead of Move.toml configuration
-- **Consistent deployment**: Same compiled bytecode deployed to all networks
-- **UpgradeCap tracking**: Captures and stores UpgradeCap object ID for future package upgrades
-
-**Prerequisites:**
-Ensure IOTA CLI environments are configured:
-
-```bash
-# Check available environments
-iota client envs
-
-# Configure networks if missing
-iota client new-env --alias testnet --rpc https://fullnode.testnet.iota.cafe:443
-iota client new-env --alias mainnet --rpc https://api.mainnet.iota.cafe
-iota client new-env --alias devnet --rpc https://api.devnet.iota.cafe
-```
-
-**Example:**
-
-```bash
-# Deploy to testnet using environment variables (recommended)
-npx move-to-json deploy --load-env configs/testnet.env --contracts tests/fixtures/smart-contract-deployments/smart-contract-deployments.json
-
-# Deploy to mainnet using environment variables (recommended)
-npx move-to-json deploy --load-env configs/mainnet.env --contracts tests/fixtures/smart-contract-deployments/smart-contract-deployments.json
-
-# Dry run (simulation)
-npx move-to-json deploy --load-env configs/testnet.env --contracts tests/fixtures/smart-contract-deployments/smart-contract-deployments.json --dry-run
-```
-
-**Output:**
-The deployment saves both Package ID and UpgradeCap ID:
-
-```json
-{
-  "testnet": {
-    "packageId": "0x...",
-    "package": "base64data...",
-    "deployedPackageId": "0x239ad3ea39f0910a4dc4c98161bcde948fb5ed0d7d7ae6d9a593239c43af748e",
-    "upgradeCap": "0xfd6269c28e3931e41aa9d9e08ffabb8162cf1fd0baaef14094b4442e6c743edf"
-  }
-}
-```
-
-**Important Note on UpgradeCap:**
-The UpgradeCap ID is crucial for package upgrades. Keep this secure - it's required to upgrade your deployed packages in the future.
-
-## Unified Move.toml Approach
-
-The tool now uses a **unified Move.toml approach** that eliminates the need for network-specific Move.toml files. This provides better consistency and reduces complexity.
-
-### Single Move.toml Configuration
-
-Instead of multiple `Move.toml.{network}` files, use a single `Move.toml` file:
-
-```toml
-[package]
-name = "my_contract"
-version = "0.0.1"
-edition = "2024.beta"
-
-[dependencies]
-Iota = {
-    git = "https://github.com/iotaledger/iota.git",
-    subdir = "crates/iota-framework/packages/iota-framework",
-    rev = "framework/testnet"
-}
-
-[addresses]
-my_contract = "0x0"
-
-[dev-dependencies]
-# Optional: Override dependencies for testing
-# Iota = { git = "https://github.com/iotaledger/iota.git", subdir = "crates/iota-framework/packages/iota-framework", rev = "framework/devnet", override = true }
-
-[dev-addresses]
-# Optional: Override addresses for development
-# my_contract = "0x1234"
-```
-
-### Framework Version Strategy
-
-- **Development/Testing**: Use `framework/testnet` for all networks
-- **Production**: Same `framework/testnet` works for mainnet deployment
-- **Consistency**: Same bytecode compiles for all target networks
-
-### Network Targeting
-
-Network targeting is handled through **IOTA CLI environments**, not Move.toml:
-
-```bash
-# Build once - same bytecode for all networks
-iota move build
-
-# Deploy to different networks by switching environments
-iota client switch --env testnet && iota client publish
-iota client switch --env mainnet && iota client publish
-```
-
-### Benefits
-
-- ✅ **Consistent builds** across all networks
-- ✅ **Reduced complexity** - no file copying
-- ✅ **Industry standard** approach
-- ✅ **Better maintainability** - single source of truth
-- ✅ **Eliminated build conflicts** between networks
-
-## Package Upgrades and UpgradeCap Management
-
-When you deploy a Move package on IOTA, the network creates an **UpgradeCap** (Upgrade Capability) object that controls the ability to upgrade that package. This tool automatically captures and stores the UpgradeCap ID for future use.
-
-### What is an UpgradeCap?
-
-The UpgradeCap is a special object that:
-
-- **Controls package upgrades**: Only the holder can upgrade the package
-- **Is created once**: Generated during initial package deployment
-- **Must be preserved**: Lost UpgradeCap = no future upgrades possible
-- **Is network-specific**: Each network deployment gets its own UpgradeCap
-
-### UpgradeCap Storage
-
-The tool stores UpgradeCap IDs in the smart-contract-deployments.json file:
-
-```json
-{
-  "testnet": {
-    "packageId": "0xabc123...",
-    "package": "base64data...",
-    "deployedPackageId": "0x239ad3ea39f0910a4dc4c98161bcde948fb5ed0d7d7ae6d9a593239c43af748e",
-    "upgradeCap": "0xfd6269c28e3931e41aa9d9e08ffabb8162cf1fd0baaef14094b4442e6c743edf"
-  }
-}
-```
-
-### Using UpgradeCap for Package Upgrades
-
-To upgrade a deployed package, you'll need the UpgradeCap ID:
-
-```bash
-# Example upgrade command (using IOTA CLI)
-iota client call --package 0x2 --module package --function upgrade \
-  --args 0xfd6269c28e3931e41aa9d9e08ffabb8162cf1fd0baaef14094b4442e6c743edf \
-  --gas-budget 50000000
-```
-
-## Known Issues
-
-### Windows
-
-#### Long Path Limitation Error
-
-**Error Symptoms:**
-
-- Build commands fail with `Failed to reset to latest Git state 'mainnet'`
-- Tests timeout during Move compilation
-- Git dependency resolution failures
-
-**Root Cause:**
-Windows has a default file path length limitation of 260 characters. The IOTA framework repository contains files with very long paths (especially in test directories) that exceed this limit, causing Git operations to fail during dependency resolution.
-
-**Solution:**
-Enable long path support in both Git and Windows:
-
-1. **Enable Git Long Paths:**
-
-   ```bash
-   git config --global core.longpaths true
-   ```
-
-2. **Enable Windows Long Path Support (requires Administrator privileges):**
-
-   ```powershell
-   # Run PowerShell as Administrator
-   Set-ItemProperty -Path 'HKLM:SYSTEM\CurrentControlSet\Control\FileSystem' -Name 'LongPathsEnabled' -Value 1
-   ```
-
-3. **Restart your computer** for Windows registry changes to take effect.
-
-**Verification:**
-After applying the fix, you should see successful Git dependency updates:
-
-```bash
-UPDATING GIT DEPENDENCY https://github.com/iotaledger/iota.git
-INCLUDING DEPENDENCY Iota
-INCLUDING DEPENDENCY MoveStdlib
-BUILDING nft
-```
-
-**Alternative Workaround:**
-If you cannot enable long path support system-wide, you can use the `--skip-fetch-latest-git-deps` flag as a workaround, though this will use cached dependencies instead of the latest versions:
-
-```bash
-iota move build --skip-fetch-latest-git-deps
-```
+The changes between each version can be found in [docs/changelog.md](docs/changelog.md)

package/dist/es/cli.js

@@ -21,7 +21,7 @@ export class CLI extends CLIBase {
         return this.execute({
             title: "TWIN Move to JSON",
             appName: "move-to-json",
-            version: "0.0.3-next.1", // x-release-please-version
+            version: "0.0.3-next.10", // x-release-please-version
             icon: "⚙️ ",
             supportsEnvFiles: true,
             overrideOutputWidth: options?.overrideOutputWidth

package/dist/es/cli.js.map

@@ -1 +1 @@
-{"version":3,"file":"cli.js","sourceRoot":"","sources":["../../src/cli.ts"],"names":[],"mappings":"AAAA,gCAAgC;AAChC,uCAAuC;AACvC,OAAO,IAAI,MAAM,WAAW,CAAC;AAC7B,OAAO,EAAE,aAAa,EAAE,MAAM,UAAU,CAAC;AACzC,OAAO,EAAE,OAAO,EAAE,MAAM,oBAAoB,CAAC;AAE7C,OAAO,EAAE,iBAAiB,EAAE,MAAM,qBAAqB,CAAC;AACxD,OAAO,EAAE,kBAAkB,EAAE,MAAM,sBAAsB,CAAC;AAE1D;;GAEG;AACH,MAAM,OAAO,GAAI,SAAQ,OAAO;IAC/B;;;;;;;OAOG;IACI,KAAK,CAAC,GAAG,CACf,IAAc,EACd,gBAAyB,EACzB,OAEC;QAED,OAAO,IAAI,CAAC,OAAO,CAClB;YACC,KAAK,EAAE,mBAAmB;YAC1B,OAAO,EAAE,cAAc;YACvB,OAAO,EAAE,cAAc,EAAE,2BAA2B;YACpD,IAAI,EAAE,KAAK;YACX,gBAAgB,EAAE,IAAI;YACtB,mBAAmB,EAAE,OAAO,EAAE,mBAAmB;SACjD,EACD,gBAAgB,IAAI,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,OAAO,CAAC,aAAa,CAAC,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,YAAY,CAAC,EACzF,IAAI,CACJ,CAAC;IACH,CAAC;IAED;;;OAGG;IACO,aAAa,CAAC,OAAgB;QACvC,iBAAiB,CAAC,OAAO,CAAC,CAAC;QAC3B,kBAAkB,CAAC,OAAO,CAAC,CAAC;IAC7B,CAAC;CACD","sourcesContent":["// Copyright 2024 IOTA Stiftung.\n// SPDX-License-Identifier: Apache-2.0.\nimport path from \"node:path\";\nimport { fileURLToPath } from \"node:url\";\nimport { CLIBase } from \"@twin.org/cli-core\";\nimport type { Command } from \"commander\";\nimport { buildCommandBuild } from \"./commands/build.js\";\nimport { buildCommandDeploy } from \"./commands/deploy.js\";\n\n/**\n * The main entry point for the Move to JSON CLI.\n */\nexport class CLI extends CLIBase {\n\t/**\n\t * Run the app.\n\t * @param argv The process arguments.\n\t * @param localesDirectory The directory for the locales, default to relative to the script.\n\t * @param options Additional options.\n\t * @param options.overrideOutputWidth Override the output width.\n\t * @returns The exit code.\n\t */\n\tpublic async run(\n\t\targv: string[],\n\t\tlocalesDirectory?: string,\n\t\toptions?: {\n\t\t\toverrideOutputWidth?: number;\n\t\t}\n\t): Promise<number> {\n\t\treturn this.execute(\n\t\t\t{\n\t\t\t\ttitle: \"TWIN Move to JSON\",\n\t\t\t\tappName: \"move-to-json\",\n\t\t\t\tversion: \"0.0.3-next.1\", // x-release-please-version\n\t\t\t\ticon: \"⚙️ \",\n\t\t\t\tsupportsEnvFiles: true,\n\t\t\t\toverrideOutputWidth: options?.overrideOutputWidth\n\t\t\t},\n\t\t\tlocalesDirectory ?? path.join(path.dirname(fileURLToPath(import.meta.url)), \"../locales\"),\n\t\t\targv\n\t\t);\n\t}\n\n\t/**\n\t * Configure any options or actions at the root program level.\n\t * @param program The root program command.\n\t */\n\tprotected configureRoot(program: Command): void {\n\t\tbuildCommandBuild(program);\n\t\tbuildCommandDeploy(program);\n\t}\n}\n"]}
+{"version":3,"file":"cli.js","sourceRoot":"","sources":["../../src/cli.ts"],"names":[],"mappings":"AAAA,gCAAgC;AAChC,uCAAuC;AACvC,OAAO,IAAI,MAAM,WAAW,CAAC;AAC7B,OAAO,EAAE,aAAa,EAAE,MAAM,UAAU,CAAC;AACzC,OAAO,EAAE,OAAO,EAAE,MAAM,oBAAoB,CAAC;AAE7C,OAAO,EAAE,iBAAiB,EAAE,MAAM,qBAAqB,CAAC;AACxD,OAAO,EAAE,kBAAkB,EAAE,MAAM,sBAAsB,CAAC;AAE1D;;GAEG;AACH,MAAM,OAAO,GAAI,SAAQ,OAAO;IAC/B;;;;;;;OAOG;IACI,KAAK,CAAC,GAAG,CACf,IAAc,EACd,gBAAyB,EACzB,OAEC;QAED,OAAO,IAAI,CAAC,OAAO,CAClB;YACC,KAAK,EAAE,mBAAmB;YAC1B,OAAO,EAAE,cAAc;YACvB,OAAO,EAAE,eAAe,EAAE,2BAA2B;YACrD,IAAI,EAAE,KAAK;YACX,gBAAgB,EAAE,IAAI;YACtB,mBAAmB,EAAE,OAAO,EAAE,mBAAmB;SACjD,EACD,gBAAgB,IAAI,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,OAAO,CAAC,aAAa,CAAC,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,YAAY,CAAC,EACzF,IAAI,CACJ,CAAC;IACH,CAAC;IAED;;;OAGG;IACO,aAAa,CAAC,OAAgB;QACvC,iBAAiB,CAAC,OAAO,CAAC,CAAC;QAC3B,kBAAkB,CAAC,OAAO,CAAC,CAAC;IAC7B,CAAC;CACD","sourcesContent":["// Copyright 2024 IOTA Stiftung.\n// SPDX-License-Identifier: Apache-2.0.\nimport path from \"node:path\";\nimport { fileURLToPath } from \"node:url\";\nimport { CLIBase } from \"@twin.org/cli-core\";\nimport type { Command } from \"commander\";\nimport { buildCommandBuild } from \"./commands/build.js\";\nimport { buildCommandDeploy } from \"./commands/deploy.js\";\n\n/**\n * The main entry point for the Move to JSON CLI.\n */\nexport class CLI extends CLIBase {\n\t/**\n\t * Run the app.\n\t * @param argv The process arguments.\n\t * @param localesDirectory The directory for the locales, default to relative to the script.\n\t * @param options Additional options.\n\t * @param options.overrideOutputWidth Override the output width.\n\t * @returns The exit code.\n\t */\n\tpublic async run(\n\t\targv: string[],\n\t\tlocalesDirectory?: string,\n\t\toptions?: {\n\t\t\toverrideOutputWidth?: number;\n\t\t}\n\t): Promise<number> {\n\t\treturn this.execute(\n\t\t\t{\n\t\t\t\ttitle: \"TWIN Move to JSON\",\n\t\t\t\tappName: \"move-to-json\",\n\t\t\t\tversion: \"0.0.3-next.10\", // x-release-please-version\n\t\t\t\ticon: \"⚙️ \",\n\t\t\t\tsupportsEnvFiles: true,\n\t\t\t\toverrideOutputWidth: options?.overrideOutputWidth\n\t\t\t},\n\t\t\tlocalesDirectory ?? path.join(path.dirname(fileURLToPath(import.meta.url)), \"../locales\"),\n\t\t\targv\n\t\t);\n\t}\n\n\t/**\n\t * Configure any options or actions at the root program level.\n\t * @param program The root program command.\n\t */\n\tprotected configureRoot(program: Command): void {\n\t\tbuildCommandBuild(program);\n\t\tbuildCommandDeploy(program);\n\t}\n}\n"]}

package/dist/es/commands/deploy.js

@@ -5,9 +5,12 @@ import path from "node:path";
 import { IotaClient } from "@iota/iota-sdk/client";
 import { requestIotaFromFaucetV0 } from "@iota/iota-sdk/faucet";
 import { CLIDisplay, CLIParam, CLIUtils } from "@twin.org/cli-core";
-import { Converter, GeneralError, Guards, I18n, Is, RandomHelper } from "@twin.org/core";
+import { Coerce, Converter, GeneralError, Guards, I18n, Is, RandomHelper } from "@twin.org/core";
 import { Bip39, Bip44 } from "@twin.org/crypto";
 import { Iota, NetworkTypes } from "@twin.org/dlt-iota";
+import { MemoryEntityStorageConnector } from "@twin.org/entity-storage-connector-memory";
+import { EntityStorageConnectorFactory } from "@twin.org/entity-storage-models";
+import { EntityStorageVaultConnector, initSchema } from "@twin.org/vault-connector-entity-storage";
 import { cleanBuildArtifactsInPath } from "../utils/buildArtifactUtils.js";
 import { ensureEnvironment, execAsyncWithError } from "../utils/environmentUtils.js";
 import { getDeploymentMnemonic, getDeploymentSeed, validateDeploymentEnvironment } from "../utils/envSetup.js";
@@ -398,6 +401,39 @@ async function determineDeploymentStrategy(contractData) {
     }
     return "initial-deploy";
 }
+/**
+ * Query the on-chain UpgradeCap object to get the actual latest package ID.
+ * This is used to validate/correct the `published-at` value before upgrades,
+ * preventing failures when the deployment JSON is stale.
+ * @param rpcUrl RPC endpoint URL for the network.
+ * @param upgradeCapabilityId The UpgradeCap object ID on-chain.
+ * @returns The on-chain package ID and version, or undefined if query fails.
+ */
+async function queryUpgradeCapPackage(rpcUrl, upgradeCapabilityId) {
+    try {
+        const client = new IotaClient({ url: rpcUrl });
+        const response = await client.getObject({
+            id: upgradeCapabilityId,
+            options: { showContent: true }
+        });
+        if (response.data?.content?.dataType === "moveObject") {
+            const fields = response.data.content.fields;
+            const fieldPackage = Coerce.string(fields.package);
+            const fieldVersion = Coerce.number(fields.version);
+            if (Is.stringValue(fieldPackage) && Is.number(fieldVersion)) {
+                return {
+                    package: fieldPackage,
+                    version: fieldVersion
+                };
+            }
+        }
+        return undefined;
+    }
+    catch {
+        // If query fails (e.g. network issue), return undefined to fall back to JSON value
+        return undefined;
+    }
+}
 /**
  * Execute contract upgrade using iota client upgrade command.
  * @param contractData Contract data containing upgrade capability.
@@ -405,10 +441,27 @@ async function determineDeploymentStrategy(contractData) {
  * @returns Upgrade result with package ID and upgrade capability.
  */
 async function executeContractUpgrade(contractData, config) {
-    // Store the previous deployedPackageId for "published-at" field in Move.toml
-    // Use lastDeployedPackageId which tracks the previous deployment for upgrade chain
-    const previousDeployedPackageId = contractData.lastDeployedPackageId;
-    if (!previousDeployedPackageId) {
+    // Start with lastDeployedPackageId from JSON as the candidate for "published-at"
+    let publishedAtPackageId = contractData.lastDeployedPackageId;
+    // Query the on-chain UpgradeCap to get the actual latest package ID.
+    // This prevents failures when the JSON is stale
+    if (Is.stringValue(contractData.upgradeCapabilityId)) {
+        CLIDisplay.task(I18n.formatMessage("commands.deploy.progress.queryingUpgradeCap"));
+        const onChainCap = await queryUpgradeCapPackage(config.rpc.url, contractData.upgradeCapabilityId);
+        if (onChainCap) {
+            CLIDisplay.value(I18n.formatMessage("commands.deploy.labels.onChainPackageId"), onChainCap.package, 1);
+            CLIDisplay.value(I18n.formatMessage("commands.deploy.labels.onChainVersion"), String(onChainCap.version), 1);
+            if (publishedAtPackageId !== onChainCap.package) {
+                CLIDisplay.value(I18n.formatMessage("commands.deploy.labels.warning"), I18n.formatMessage("commands.deploy.messages.staleJsonDetected", {
+                    jsonPackageId: publishedAtPackageId ?? "none",
+                    onChainPackageId: onChainCap.package
+                }), 2);
+                publishedAtPackageId = onChainCap.package;
+                contractData.lastDeployedPackageId = onChainCap.package;
+            }
+        }
+    }
+    if (!publishedAtPackageId) {
         throw new GeneralError("commands", "commands.deploy.noPreviousDeploymentForUpgrade");
     }
     const moveTomlPaths = [];
@@ -424,8 +477,8 @@ async function executeContractUpgrade(contractData, config) {
     const projectRoot = path.dirname(moveTomlPath);
     const backupPath = await backupMoveToml(moveTomlPath);
     try {
-        // Update Move.toml with "published-at" = previous deployedPackageId
-        await updateMoveTomlPublishedAt(moveTomlPath, previousDeployedPackageId);
+        // Update Move.toml with "published-at" = validated package ID (from chain or JSON)
+        await updateMoveTomlPublishedAt(moveTomlPath, publishedAtPackageId);
         await validateContractIsBuilt(contractData, projectRoot);
         // Execute upgrade command
         const upgradeCapabilityId = contractData.upgradeCapabilityId;
@@ -624,6 +677,7 @@ async function deployContract(contractName, contractData, config, network, dryRu
  * @returns The wallet address.
  */
 async function getDeploymentWalletAddress(network, addressIndex, deployerMnemonic, deployerSeed) {
+    const vault = setupVault();
     // Try to use seed first if available
     const hexSeed = await getDeploymentSeed(network, deployerSeed);
     let seed;
@@ -632,10 +686,27 @@ async function getDeploymentWalletAddress(network, addressIndex, deployerMnemoni
     }
     else {
         const mnemonic = await getDeploymentMnemonic(network, deployerMnemonic);
+        await vault.setSecret("deployment/mnemonic", mnemonic);
         seed = Bip39.mnemonicToSeed(mnemonic);
     }
-    const addresses = Iota.getAddresses(seed, Iota.DEFAULT_COIN_TYPE, 0, addressIndex, 1, false);
-    return addresses[0];
+    await vault.setSecret("deployment/seed", seed);
+    return Iota.getAddress(vault, {}, "deployment", 0, addressIndex);
+}
+/**
+ * Setup vault connectors for storing deployment keys and secrets.
+ * @returns An instance of IVaultConnector for use in deployment.
+ */
+function setupVault() {
+    initSchema();
+    const keyEntityStorage = new MemoryEntityStorageConnector({
+        entitySchema: "VaultKey"
+    });
+    const secretEntityStorage = new MemoryEntityStorageConnector({
+        entitySchema: "VaultSecret"
+    });
+    EntityStorageConnectorFactory.register("vault-key", () => keyEntityStorage);
+    EntityStorageConnectorFactory.register("vault-secret", () => secretEntityStorage);
+    return new EntityStorageVaultConnector();
 }
 /**
  * Convert nanos to IOTA (1 IOTA = 1,000,000,000 nanos).