feat(1644): contract delete command expansion (#1693)

Signed-off-by: rozekmichal <michal.rozek@blockydevs.com>

Author: rozekmichal

skills/hiero-cli/references/contract.md

@@ -73,16 +73,24 @@ hcli contract import --contract 0xAbCd1234... --alias myAlias
 
 ### `hcli contract delete`
 
-Remove a contract from local state (does NOT delete from the Hedera network).
+**Default:** submits `ContractDeleteTransaction` on Hedera, then removes the contract from local CLI state. **With `--state-only`:** only removes it from local CLI state (no network transaction). Hedera does not allow deleting a contract on the network if it has no admin key; in that case use `--state-only` for local cleanup only. When the contract has an admin key, pass `--admin-key` (or keep a stored admin reference from `contract create --admin-key`) if signing material is not already in state.
 
-| Option       | Short | Type   | Required | Default | Description                      |
-| ------------ | ----- | ------ | -------- | ------- | -------------------------------- |
-| `--contract` | `-c`  | string | **yes**  | —       | Contract ID (`0.0.xxx`) or alias |
+⚠️ Requires confirmation unless using `--confirm` / script mode.
+
+| Option                   | Short | Type       | Required | Default | Description                                                                                                               |
+| ------------------------ | ----- | ---------- | -------- | ------- | ------------------------------------------------------------------------------------------------------------------------- |
+| `--contract`             | `-c`  | string     | **yes**  | —       | Contract ID (`0.0.xxx`) or alias; for network delete, state entry optional if mirror can resolve ID                       |
+| `--state-only`           | `-s`  | boolean    | no       | `false` | Remove only from local CLI state; do not submit a network delete                                                          |
+| `--transfer-id`          | `-t`  | string     | no†      | —       | Account receiving remaining HBAR (ID or alias). †One of `-t` or `-r` required for network delete. Not with `--state-only` |
+| `--transfer-contract-id` | `-r`  | string     | no†      | —       | Contract receiving remaining HBAR. †One of `-t` or `-r` required for network delete. Not with `--state-only`              |
+| `--admin-key`            | `-a`  | repeatable | no       | —       | Admin key if not stored in state (same as create). Not with `--state-only`                                                |
+| `--key-manager`          | `-k`  | string     | no       | config  | Key manager when resolving `--admin-key`                                                                                  |
 
 **Example:**
 
 ```
-hcli contract delete --contract myErc20
+hcli contract delete --contract myErc20 --transfer-id 0.0.1234 --confirm
+hcli contract delete --contract 0.0.123456 --state-only --confirm
 ```
 
-**Output:** `{ contractId, deleted }`
+**Output:** `{ deletedContract, network, removedAliases?, transactionId?, stateOnly? }`

src/__tests__/mocks/fixtures.ts

@@ -27,6 +27,7 @@ export const MOCK_PUBLIC_KEY =
   '0000000000000000000000000000000000000000000000000000000000000000';
 
 export const MOCK_CONTRACT_ID = '0.0.1234';
+export const MOCK_CONTRACT_ID_UNKNOWN = '0.0.9999';
 export const MOCK_ACCOUNT_ID = '0.0.5678';
 export const MOCK_ACCOUNT_ID_ALT = '0.0.5679';
 export const MOCK_TOPIC_ID = '0.0.7777';

src/__tests__/mocks/mocks.ts

@@ -492,6 +492,8 @@ const makePluginManagementServiceMock = (): PluginManagementService =>
 const makeContractTransactionServiceMock = (): ContractTransactionService =>
   ({
     contractCreateFlowTransaction: jest.fn(),
+    contractExecuteTransaction: jest.fn(),
+    deleteContract: jest.fn(),
   }) as unknown as ContractTransactionService;
 
 const makeContractVerifierServiceMock = (): ContractVerifierService =>

src/core/services/contract-transaction/contract-transaction-service.interface.ts

@@ -1,8 +1,10 @@
 import type {
   ContractCreateFlowParams,
   ContractCreateFlowResult,
+  ContractDeleteResult,
   ContractExecuteParams,
   ContractExecuteResult,
+  DeleteContractParams,
 } from '@/core/services/contract-transaction/types';
 
 export interface ContractTransactionService {
@@ -18,4 +20,8 @@ export interface ContractTransactionService {
   contractExecuteTransaction(
     params: ContractExecuteParams,
   ): ContractExecuteResult;
+  /**
+   * Build a ContractDeleteTransaction (sign with contract admin key + operator)
+   */
+  deleteContract(params: DeleteContractParams): ContractDeleteResult;
 }

src/core/services/contract-transaction/contract-transaction-service.ts

@@ -2,17 +2,23 @@ import type { ContractTransactionService } from '@/core/services/contract-transa
 import type {
   ContractCreateFlowParams,
   ContractCreateFlowResult,
+  ContractDeleteResult,
   ContractExecuteParams,
   ContractExecuteResult,
+  DeleteContractParams,
 } from '@/core/services/contract-transaction/types';
 
 import {
+  AccountId,
   ContractCreateFlow,
+  ContractDeleteTransaction,
   ContractExecuteTransaction,
   ContractId,
 } from '@hashgraph/sdk';
 import { ethers, getBytes } from 'ethers';
 
+import { ValidationError } from '@/core/errors';
+
 export class ContractTransactionServiceImpl implements ContractTransactionService {
   contractCreateFlowTransaction(
     params: ContractCreateFlowParams,
@@ -53,4 +59,32 @@ export class ContractTransactionServiceImpl implements ContractTransactionServic
       transaction: contractExecuteTx,
     };
   }
+
+  deleteContract(params: DeleteContractParams): ContractDeleteResult {
+    try {
+      const transaction = new ContractDeleteTransaction().setContractId(
+        ContractId.fromString(params.contractId),
+      );
+      if (params.transferAccountId) {
+        transaction.setTransferAccountId(
+          AccountId.fromString(params.transferAccountId),
+        );
+      }
+      if (params.transferContractId) {
+        transaction.setTransferContractId(
+          ContractId.fromString(params.transferContractId),
+        );
+      }
+      return { transaction };
+    } catch (error) {
+      throw new ValidationError('Invalid contract delete parameters', {
+        context: {
+          contractId: params.contractId,
+          transferAccountId: params.transferAccountId,
+          transferContractId: params.transferContractId,
+        },
+        cause: error,
+      });
+    }
+  }
 }

src/core/services/contract-transaction/types.ts

@@ -1,5 +1,6 @@
 import type {
   ContractCreateFlow,
+  ContractDeleteTransaction,
   ContractExecuteTransaction,
   ContractFunctionParameters,
   Key,
@@ -28,3 +29,13 @@ export interface ContractExecuteParams {
 export interface ContractExecuteResult {
   transaction: ContractExecuteTransaction;
 }
+
+export interface DeleteContractParams {
+  contractId: string;
+  transferAccountId?: string;
+  transferContractId?: string;
+}
+
+export interface ContractDeleteResult {
+  transaction: ContractDeleteTransaction;
+}

src/plugins/contract/README.md

@@ -16,23 +16,19 @@ This plugin follows the plugin architecture principles:
 
 ```
 src/plugins/contract/
-├── manifest.ts              # Plugin manifest with command definitions
-├── schema.ts                # Contract data schema with Zod validation
+├── manifest.ts
+├── schema.ts
+├── contract-helper.ts       # Local state cleanup after delete
 ├── commands/
 │   ├── create/
-│   │   ├── handler.ts      # Contract creation handler
-│   │   ├── input.ts        # Input schema and validation
-│   │   ├── output.ts       # Output schema and template
-│   │   └── index.ts        # Command exports
-│   └── list/
-│       ├── handler.ts      # List contracts handler
-│       ├── output.ts       # Output schema and template
-│       └── index.ts        # Command exports
+│   ├── import/
+│   ├── list/
+│   └── delete/
 ├── utils/
-│   └── contract-file-helpers.ts  # Contract file reading utilities
-├── zustand-state-helper.ts # State management helper
-├── __tests__/unit/         # Unit tests
-└── index.ts               # Plugin exports
+│   └── contract-file-helpers.ts
+├── zustand-state-helper.ts
+├── __tests__/unit/
+└── index.ts
 ```
 
 ## 🚀 Commands
@@ -95,6 +91,16 @@ hcli contract create --name my-nft --default erc721
 hcli contract create --name my-token --default erc20 -c "CustomToken" -c "CTK" -c "500000"
 ```
 
+### Contract Import
+
+Imports an existing contract from Hedera (by contract ID or EVM address) into local state.
+
+**Main options:** `--contract` (`-c`, required), optional `--name`, `--alias`, `--verified`.
+
+```bash
+hcli contract import --contract 0.0.123456 --name myContract
+```
+
 ### Contract List
 
 Lists all deployed contracts stored in the state across all networks.
@@ -103,17 +109,29 @@ Lists all deployed contracts stored in the state across all networks.
 hcli contract list
 ```
 
+### Contract Delete
+
+**Default:** submits `ContractDeleteTransaction` on Hedera, then removes the contract from local CLI state. **With `--state-only`:** only removes from local CLI state (no network transaction).
+
+When deleting on Hedera (default), pass **`--transfer-id` (`-t`)** or **`--transfer-contract-id` (`-r`)** so remaining HBAR has a destination (avoids `OBTAINER_REQUIRED` from the network). Use `--admin-key` when signing material for the contract admin key is not already in state (same formats as create). Contracts **without** an admin key on Hedera cannot be deleted on the network—use `--state-only` to drop local CLI state only. If the contract is not in local state, the CLI loads contract info from the mirror node.
+
+```bash
+hcli contract delete --contract myAlias --transfer-id 0.0.5678
+hcli contract delete --contract 0.0.123456 --state-only
+```
+
 ## 🔧 Core API Integration
 
 The plugin uses the Core API services:
 
-- `api.contract` - Contract deployment transaction creation
+- `api.contract` - Contract deployment and `ContractDeleteTransaction` construction
 - `api.contractCompiler` - Solidity compilation
 - `api.contractVerifier` - HashScan verification
-- `api.txExecution` - Transaction signing and execution
+- `api.txSign` / `api.txExecute` - Signing and execution (including contract create flow)
 - `api.state` - Namespaced state management
 - `api.network` - Network information
 - `api.alias` - Name registration and resolution
+- `api.mirror` - Contract info when deleting on network without a local state entry
 - `api.config` - Configuration (key manager default)
 - `api.keyResolver` - Key resolution for admin key
 - `api.logger` - Logging
@@ -131,7 +149,9 @@ interface CommandResult {
 **Output schemas:**
 
 - **Create**: `contractId`, `contractName`, `contractEvmAddress`, `alias`, `network`, `transactionId`, `adminPublicKey`
+- **Import**: `contractId`, `contractName`, `contractEvmAddress`, `alias`, `network`, `memo`, `verified`
 - **List**: `contracts` (array with `contractId`, `contractName`, `contractEvmAddress`, `alias`, `adminPublicKey`, `network`), `totalCount`
+- **Delete**: `deletedContract`, `network`, optional `removedAliases`, `transactionId`, `stateOnly`
 
 Human-readable output uses Handlebars templates with HashScan links for contract and transaction IDs.
 
@@ -142,12 +162,14 @@ Contract data is stored in the `contract-contracts` namespace with the following
 ```typescript
 interface ContractData {
   contractId: string; // Hedera contract ID (0.0.xxxxx)
-  contractName: string; // Contract name from Solidity source
-  contractEvmAddress: string; // Deployed EVM address
-  adminPublicKey?: string; // Optional admin public key
+  alias?: string; // Local alias for `--contract` lookups (optional)
+  contractName?: string; // Human-readable name (e.g. from Solidity or import)
+  contractEvmAddress: string; // Deployed contract EVM address
+  adminPublicKey?: string; // Optional admin public key (from network / create)
+  adminKeyRefId?: string; // KMS key ref for admin when set at create (for signing delete on network)
   network: SupportedNetwork; // Network
   memo?: string; // Optional memo (max 100 chars)
-  verified?: boolean; // Contract verification status
+  verified?: boolean; // Contract verification status (e.g. HashScan)
 }
 ```