feat(deploy-sdk): deploy sdk core artifact api implementation (#8147)

Co-authored-by: Claude Sonnet 4.5 (1M context) <noreply@anthropic.com>

Author: xeno097

.changeset/deploy-sdk-core-artifact-api.md

@@ -0,0 +1,5 @@
+---
+'@hyperlane-xyz/deploy-sdk': minor
+---
+
+Added `CoreWriter` and `CoreArtifactReader` for coordinating core deployments using the Artifact API pattern. The `CoreWriter` orchestrates mailbox, ISM, hook, and validator announce deployments with support for both create and update flows. Updated `AltVMCoreModule` to handle `UnsetArtifactAddress` in derived core configs.

.changeset/provider-sdk-core-artifact-api.md

@@ -0,0 +1,5 @@
+---
+'@hyperlane-xyz/provider-sdk': minor
+---
+
+Added `toDeployedOrUndefined` utility and `UnsetArtifactAddress` type to the artifact module. Extended `ProtocolProvider` interface with `createMailboxArtifactManager` and `createValidatorAnnounceArtifactManager` methods. Updated `mailboxArtifactToDerivedCoreConfig` to handle UNDERIVED artifacts with zero addresses gracefully. Widened `DerivedCoreConfig` fields to accept `UnsetArtifactAddress`.

typescript/aleo-sdk/src/clients/protocol.ts

@@ -13,22 +13,26 @@ import {
 import { type IProvider } from '@hyperlane-xyz/provider-sdk/altvm';
 import { type IRawHookArtifactManager } from '@hyperlane-xyz/provider-sdk/hook';
 import { type IRawIsmArtifactManager } from '@hyperlane-xyz/provider-sdk/ism';
+import { type IRawMailboxArtifactManager } from '@hyperlane-xyz/provider-sdk/mailbox';
 import {
   type AnnotatedTx,
   type TxReceipt,
 } from '@hyperlane-xyz/provider-sdk/module';
 import { type IRawWarpArtifactManager } from '@hyperlane-xyz/provider-sdk/warp';
+import { type IRawValidatorAnnounceArtifactManager } from '@hyperlane-xyz/provider-sdk/validator-announce';
 import { assert } from '@hyperlane-xyz/utils';
 
 import { AleoHookArtifactManager } from '../hook/hook-artifact-manager.js';
 import { AleoIsmArtifactManager } from '../ism/ism-artifact-manager.js';
+import { AleoMailboxArtifactManager } from '../mailbox/mailbox-artifact-manager.js';
 import {
   fromAleoAddress,
   getNetworkPrefix,
   getProgramIdFromSuffix,
   getProgramSuffix,
 } from '../utils/helper.js';
-import { AleoNetworkId } from '../utils/types.js';
+import { AleoNetworkId, toAleoNetworkId } from '../utils/types.js';
+import { AleoValidatorAnnounceArtifactManager } from '../validator-announce/validator-announce-artifact-manager.js';
 import { AleoWarpArtifactManager } from '../warp/warp-artifact-manager.js';
 
 import { AleoProvider } from './provider.js';
@@ -144,6 +148,48 @@ export class AleoProtocolProvider implements ProtocolProvider {
     });
   }
 
+  createMailboxArtifactManager(
+    chainMetadata: ChainMetadataForAltVM,
+  ): IRawMailboxArtifactManager {
+    const aleoNetworkId = toAleoNetworkId(
+      parseInt(chainMetadata.chainId.toString()),
+    );
+
+    const [rpcUrl] = chainMetadata.rpcUrls?.map(({ http }) => http) ?? [];
+    assert(rpcUrl, 'got no rpcUrls');
+
+    const aleoClient =
+      aleoNetworkId === AleoNetworkId.MAINNET
+        ? new AleoMainnetNetworkClient(rpcUrl)
+        : new AleoTestnetNetworkClient(rpcUrl);
+
+    return new AleoMailboxArtifactManager(
+      { domainId: chainMetadata.domainId, aleoNetworkId },
+      aleoClient,
+    );
+  }
+
+  createValidatorAnnounceArtifactManager(
+    chainMetadata: ChainMetadataForAltVM,
+  ): IRawValidatorAnnounceArtifactManager | null {
+    const aleoNetworkId = toAleoNetworkId(
+      parseInt(chainMetadata.chainId.toString()),
+    );
+
+    const [rpcUrl] = chainMetadata.rpcUrls?.map(({ http }) => http) ?? [];
+    assert(rpcUrl, 'got no rpcUrls');
+
+    const aleoClient =
+      aleoNetworkId === AleoNetworkId.MAINNET
+        ? new AleoMainnetNetworkClient(rpcUrl)
+        : new AleoTestnetNetworkClient(rpcUrl);
+
+    return new AleoValidatorAnnounceArtifactManager(
+      { domainId: chainMetadata.domainId, aleoNetworkId },
+      aleoClient,
+    );
+  }
+
   getMinGas(): MinimumRequiredGasByAction {
     return {
       CORE_DEPLOY_GAS: 0n,

typescript/cosmos-sdk/src/clients/protocol.ts

@@ -10,11 +10,13 @@ import {
 import { type IProvider } from '@hyperlane-xyz/provider-sdk/altvm';
 import { type IRawHookArtifactManager } from '@hyperlane-xyz/provider-sdk/hook';
 import { type IRawIsmArtifactManager } from '@hyperlane-xyz/provider-sdk/ism';
+import { type IRawMailboxArtifactManager } from '@hyperlane-xyz/provider-sdk/mailbox';
 import {
   type AnnotatedTx,
   type TxReceipt,
 } from '@hyperlane-xyz/provider-sdk/module';
 import { type IRawWarpArtifactManager } from '@hyperlane-xyz/provider-sdk/warp';
+import { type IRawValidatorAnnounceArtifactManager } from '@hyperlane-xyz/provider-sdk/validator-announce';
 import { assert } from '@hyperlane-xyz/utils';
 
 import { CosmosHookArtifactManager } from '../hook/hook-artifact-manager.js';
@@ -23,6 +25,7 @@ import { CosmosWarpArtifactManager } from '../warp/warp-artifact-manager.js';
 
 import { CosmosNativeProvider } from './provider.js';
 import { CosmosNativeSigner } from './signer.js';
+import { CosmosMailboxArtifactManager } from '../mailbox/mailbox-artifact-manager.js';
 
 export class CosmosNativeProtocolProvider implements ProtocolProvider {
   createProvider(chainMetadata: ChainMetadataForAltVM): Promise<IProvider> {
@@ -92,6 +95,29 @@ export class CosmosNativeProtocolProvider implements ProtocolProvider {
     return new CosmosWarpArtifactManager(rpcUrls);
   }
 
+  createMailboxArtifactManager(
+    chainMetadata: ChainMetadataForAltVM,
+  ): IRawMailboxArtifactManager {
+    const [rpcUrl, ...otherRpcUrls] =
+      chainMetadata.rpcUrls?.map((rpc) => rpc.http) ?? [];
+    assert(
+      rpcUrl,
+      `Expected at least one rpc url for chain ${chainMetadata.name}`,
+    );
+
+    return new CosmosMailboxArtifactManager({
+      domainId: chainMetadata.domainId,
+      rpcUrls: [rpcUrl, ...otherRpcUrls],
+    });
+  }
+
+  createValidatorAnnounceArtifactManager(
+    _chainMetadata: ChainMetadataForAltVM,
+  ): IRawValidatorAnnounceArtifactManager | null {
+    // Cosmos does not support validator announce
+    return null;
+  }
+
   getMinGas(): MinimumRequiredGasByAction {
     return {
       CORE_DEPLOY_GAS: BigInt(1e6),

typescript/deploy-sdk/src/AltVMCoreModule.ts

@@ -24,7 +24,13 @@ import {
   HypModuleArgs,
   TxReceipt,
 } from '@hyperlane-xyz/provider-sdk/module';
-import { Address, Logger, rootLogger } from '@hyperlane-xyz/utils';
+import {
+  Address,
+  Logger,
+  eqAddress,
+  isEmptyAddress,
+  rootLogger,
+} from '@hyperlane-xyz/utils';
 
 import { AltVMCoreReader } from './AltVMCoreReader.js';
 import { createHookWriter } from './hook/hook-writer.js';
@@ -289,6 +295,10 @@ export class AltVMCoreModule implements HypModule<CoreModuleType> {
     const updateTransactions: AnnotatedTx[] = [];
 
     const actualDefaultIsmConfig = actualConfig.defaultIsm;
+    const actualIsmAddress =
+      typeof actualDefaultIsmConfig === 'string'
+        ? actualDefaultIsmConfig
+        : actualDefaultIsmConfig.address;
 
     // Try to update (may also deploy) Ism with the expected config
     const { deployedIsm, ismUpdateTxs } = await this.deployOrUpdateIsm(
@@ -300,11 +310,11 @@ export class AltVMCoreModule implements HypModule<CoreModuleType> {
       updateTransactions.push(...ismUpdateTxs);
     }
 
-    const newIsmDeployed = actualDefaultIsmConfig.address !== deployedIsm;
+    const newIsmDeployed = !eqAddress(actualIsmAddress, deployedIsm);
     if (newIsmDeployed) {
       const { mailbox } = this.serialize();
       updateTransactions.push({
-        annotation: `Updating default ISM of Mailbox from ${actualDefaultIsmConfig.address} to ${deployedIsm}`,
+        annotation: `Updating default ISM of Mailbox from ${actualIsmAddress} to ${deployedIsm}`,
         ...(await this.signer.getSetDefaultIsmTransaction({
           signer: actualConfig.owner,
           mailboxAddress: mailbox,
@@ -322,7 +332,7 @@ export class AltVMCoreModule implements HypModule<CoreModuleType> {
    * @returns Object with deployedIsm address, and update Transactions
    */
   public async deployOrUpdateIsm(
-    actualDefaultIsmConfig: DerivedIsmConfig,
+    actualDefaultIsmConfig: DerivedIsmConfig | string,
     expectDefaultIsmConfig: IsmConfig | string,
   ): Promise<{
     deployedIsm: Address;
@@ -343,15 +353,29 @@ export class AltVMCoreModule implements HypModule<CoreModuleType> {
       this.signer,
     );
 
-    // Read actual ISM state
-    const actualArtifact = await writer.read(actualDefaultIsmConfig.address);
-
     // Convert expected config to artifact format
     const expectedArtifact = ismConfigToArtifact(
       expectDefaultIsmConfig,
       this.chainLookup,
     );
 
+    // No existing ISM on chain — deploy the expected one directly
+    const actualIsmAddress =
+      typeof actualDefaultIsmConfig === 'string'
+        ? actualDefaultIsmConfig
+        : actualDefaultIsmConfig.address;
+
+    if (isEmptyAddress(actualIsmAddress)) {
+      const [deployed] = await writer.create(expectedArtifact);
+      return {
+        deployedIsm: deployed.deployed.address,
+        ismUpdateTxs: [],
+      };
+    }
+
+    // Read actual ISM state
+    const actualArtifact = await writer.read(actualIsmAddress);
+
     this.logger.info(
       `Comparing target ISM config with ${this.args.chain} chain`,
     );
@@ -391,6 +415,10 @@ export class AltVMCoreModule implements HypModule<CoreModuleType> {
     const updateTransactions: AnnotatedTx[] = [];
 
     const actualDefaultHookConfig = actualConfig.defaultHook;
+    const actualDefaultHookAddress =
+      typeof actualDefaultHookConfig === 'string'
+        ? actualDefaultHookConfig
+        : actualDefaultHookConfig.address;
 
     // Try to update (may also deploy) Hook with the expected config
     const { deployedHook, hookUpdateTxs } = await this.deployOrUpdateHook(
@@ -402,11 +430,11 @@ export class AltVMCoreModule implements HypModule<CoreModuleType> {
       updateTransactions.push(...hookUpdateTxs);
     }
 
-    const newHookDeployed = actualDefaultHookConfig.address !== deployedHook;
+    const newHookDeployed = !eqAddress(actualDefaultHookAddress, deployedHook);
     if (newHookDeployed) {
       const { mailbox } = this.serialize();
       updateTransactions.push({
-        annotation: `Updating default Hook of Mailbox from ${actualDefaultHookConfig.address} to ${deployedHook}`,
+        annotation: `Updating default Hook of Mailbox from ${actualDefaultHookAddress} to ${deployedHook}`,
         ...(await this.signer.getSetDefaultHookTransaction({
           signer: actualConfig.owner,
           mailboxAddress: mailbox,
@@ -432,6 +460,10 @@ export class AltVMCoreModule implements HypModule<CoreModuleType> {
     const updateTransactions: AnnotatedTx[] = [];
 
     const actualRequiredHookConfig = actualConfig.requiredHook;
+    const actualRequiredHookAddress =
+      typeof actualRequiredHookConfig === 'string'
+        ? actualRequiredHookConfig
+        : actualRequiredHookConfig.address;
 
     // Try to update (may also deploy) Hook with the expected config
     const { deployedHook, hookUpdateTxs } = await this.deployOrUpdateHook(
@@ -443,11 +475,11 @@ export class AltVMCoreModule implements HypModule<CoreModuleType> {
       updateTransactions.push(...hookUpdateTxs);
     }
 
-    const newHookDeployed = actualRequiredHookConfig.address !== deployedHook;
+    const newHookDeployed = !eqAddress(actualRequiredHookAddress, deployedHook);
     if (newHookDeployed) {
       const { mailbox } = this.serialize();
       updateTransactions.push({
-        annotation: `Updating required Hook of Mailbox from ${actualRequiredHookConfig.address} to ${deployedHook}`,
+        annotation: `Updating required Hook of Mailbox from ${actualRequiredHookAddress} to ${deployedHook}`,
         ...(await this.signer.getSetRequiredHookTransaction({
           signer: actualConfig.owner,
           mailboxAddress: mailbox,
@@ -465,7 +497,7 @@ export class AltVMCoreModule implements HypModule<CoreModuleType> {
    * @returns Object with deployedHook address, and update Transactions
    */
   public async deployOrUpdateHook(
-    actualHookConfig: DerivedHookConfig,
+    actualHookConfig: DerivedHookConfig | string,
     expectHookConfig: HookConfig | string,
   ): Promise<{
     deployedHook: Address;
@@ -493,9 +525,14 @@ export class AltVMCoreModule implements HypModule<CoreModuleType> {
       `Comparing target Hook config with ${this.args.chain} chain`,
     );
 
+    const actualHookAddress =
+      typeof actualHookConfig === 'string'
+        ? actualHookConfig
+        : actualHookConfig.address;
+
     // Use the new deployOrUpdate method from HookWriter
     const result = await writer.deployOrUpdate({
-      actualAddress: actualHookConfig.address,
+      actualAddress: actualHookAddress,
       expectedConfig: expectHookConfig,
     });