feat(aleo-sdk): aleo core artifact api implementation (#8142)

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

Author: xeno097

.changeset/aleo-core-artifacts.md

@@ -0,0 +1,5 @@
+---
+"@hyperlane-xyz/aleo-sdk": minor
+---
+
+Implemented mailbox and validator announce artifact API for Aleo protocol, enabling deployment and configuration management through the unified artifact pattern.

.github/workflows/test-sdk-e2e.yml

@@ -53,6 +53,11 @@ jobs:
           - 4_warp
           - 5_ism_artifacts
           - 6_hook_artifacts
+          - 7a_warp_native_artifacts
+          - 7b_warp_collateral_artifacts
+          - 7c_warp_synthetic_artifacts
+          - 8_mailbox_artifacts
+          - 9_validator_announce_artifacts
     steps:
       - uses: actions/checkout@v6
         with:

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

@@ -18,11 +18,11 @@ import {
 import { assert, retryAsync } from '@hyperlane-xyz/utils';
 
 import {
-  MAINNET_PREFIX,
+  getNetworkPrefix,
   RETRY_ATTEMPTS,
   RETRY_DELAY_MS,
-  TESTNET_PREFIX,
 } from '../utils/helper.js';
+import { toAleoNetworkId } from '../utils/types.js';
 
 export type AnyAleoNetworkClient =
   | AleoMainnetNetworkClient
@@ -44,18 +44,15 @@ export class AleoBase {
   protected readonly warpSuffix: string;
 
   constructor(rpcUrls: string[], chainId: string | number) {
-    assert(
-      +chainId === 0 || +chainId === 1,
-      `Unknown chain id ${chainId} for Aleo, only 0 or 1 allowed`,
-    );
+    const aleoNetworkId = toAleoNetworkId(+chainId);
     assert(rpcUrls.length > 0, `got no rpcUrls`);
 
     // because the aleo provable sdk appends /testnet or /mainnet to the base
     // rpc automatically we need to remove it here
     this.rpcUrls = rpcUrls.map((r) =>
       r.replaceAll('/testnet', '').replaceAll('/mainnet', ''),
     );
-    this.chainId = +chainId;
+    this.chainId = aleoNetworkId;
 
     this.aleoClient = this.chainId
       ? new AleoTestnetNetworkClient(this.rpcUrls[0])
@@ -72,7 +69,7 @@ export class AleoBase {
       getOrInitConsensusVersionTestHeights(this.consensusVersionHeights);
     }
 
-    this.prefix = this.chainId ? TESTNET_PREFIX : MAINNET_PREFIX;
+    this.prefix = getNetworkPrefix(aleoNetworkId);
 
     this.ismManager = process.env['ALEO_ISM_MANAGER_SUFFIX']
       ? `${this.prefix}_ism_manager_${process.env['ALEO_ISM_MANAGER_SUFFIX']}.aleo`
@@ -81,6 +78,10 @@ export class AleoBase {
     this.warpSuffix = process.env['ALEO_WARP_SUFFIX'] || '';
   }
 
+  getAleoClient(): AnyAleoNetworkClient {
+    return this.aleoClient;
+  }
+
   protected getProgramManager(privateKey?: string): AnyProgramManager {
     if (this.chainId) {
       const account = privateKey

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

@@ -23,9 +23,8 @@ import { assert } from '@hyperlane-xyz/utils';
 import { AleoHookArtifactManager } from '../hook/hook-artifact-manager.js';
 import { AleoIsmArtifactManager } from '../ism/ism-artifact-manager.js';
 import {
-  MAINNET_PREFIX,
-  TESTNET_PREFIX,
   fromAleoAddress,
+  getNetworkPrefix,
   getProgramIdFromSuffix,
   getProgramSuffix,
 } from '../utils/helper.js';
@@ -123,8 +122,7 @@ export class AleoProtocolProvider implements ProtocolProvider {
         ? new AleoMainnetNetworkClient(rpcUrl)
         : new AleoTestnetNetworkClient(rpcUrl);
 
-    const prefix =
-      chainId === AleoNetworkId.TESTNET ? TESTNET_PREFIX : MAINNET_PREFIX;
+    const prefix = getNetworkPrefix(chainId);
     const customIsmSuffix = process.env['ALEO_ISM_MANAGER_SUFFIX'];
     const ismManagerAddress = customIsmSuffix
       ? `${prefix}_ism_manager_${customIsmSuffix}.aleo`

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

@@ -9,8 +9,8 @@ import {
   SUFFIX_LENGTH_LONG,
   SUFFIX_LENGTH_SHORT,
   fromAleoAddress,
-  getProgramIdFromSuffix,
   getProgramSuffix,
+  getUnusedSuffix,
   loadProgramsInDeployOrder,
   programIdToPlaintext,
   toAleoAddress,
@@ -32,7 +32,7 @@ export class AleoSigner
     rpcUrls: string[],
     privateKey: string,
     extraParams?: Record<string, any>,
-  ): Promise<AltVM.ISigner<AleoTransaction, AleoReceipt>> {
+  ): Promise<AleoSigner> {
     assert(extraParams, `extra params not defined`);
 
     const metadata = extraParams.metadata as Record<string, unknown>;
@@ -91,28 +91,6 @@ export class AleoSigner
     );
   }
 
-  private async getUnusedSuffix(
-    programName: AleoProgram,
-    length: number,
-    maxAttempts = 20,
-  ): Promise<string> {
-    for (let i = 0; i < maxAttempts; i++) {
-      const suffix = this.generateSuffix(length);
-      const programId = getProgramIdFromSuffix(
-        this.prefix,
-        programName,
-        suffix,
-      );
-      if (!(await this.isProgramDeployed(programId))) {
-        return suffix;
-      }
-    }
-
-    throw new Error(
-      `Could not find an unused suffix for ${programName} after ${maxAttempts} attempts`,
-    );
-  }
-
   async getWarpTokenSuffix(
     tokenType: TokenType,
     preferredSuffix?: string,
@@ -264,7 +242,9 @@ export class AleoSigner
       );
     }
 
-    const mailboxSuffix = await this.getUnusedSuffix(
+    const mailboxSuffix = await getUnusedSuffix(
+      this.aleoClient,
+      this.prefix,
       'mailbox',
       SUFFIX_LENGTH_LONG,
     );

typescript/aleo-sdk/src/hook/hook-artifact-manager.ts

@@ -67,10 +67,8 @@ export class AleoHookArtifactManager implements IRawHookArtifactManager {
         new AleoIgpHookReader(this.aleoClient),
     };
 
-    const maybeReader = readers[type]();
-
-    assert(maybeReader, `Hook writer for ${type} not found`);
-    return maybeReader;
+    assert(readers[type], `Hook reader for ${type} not found`);
+    return readers[type]();
   }
 
   createWriter<T extends HookType>(
@@ -92,9 +90,7 @@ export class AleoHookArtifactManager implements IRawHookArtifactManager {
         new AleoIgpHookWriter(this.aleoClient, signer, mailboxAddress),
     };
 
-    const maybeWriter = writers[type]();
-
-    assert(maybeWriter, `Hook writer for ${type} not found`);
-    return maybeWriter;
+    assert(writers[type], `Hook writer for ${type} not found`);
+    return writers[type]();
   }
 }

typescript/aleo-sdk/src/index.ts

@@ -14,3 +14,10 @@ export {
 } from './hook/merkle-tree-hook.js';
 export { AleoIgpHookReader, AleoIgpHookWriter } from './hook/igp-hook.js';
 export { AleoWarpArtifactManager } from './warp/warp-artifact-manager.js';
+export { AleoMailboxArtifactManager } from './mailbox/mailbox-artifact-manager.js';
+export { AleoMailboxReader, AleoMailboxWriter } from './mailbox/mailbox.js';
+export { AleoValidatorAnnounceArtifactManager } from './validator-announce/validator-announce-artifact-manager.js';
+export {
+  AleoValidatorAnnounceReader,
+  AleoValidatorAnnounceWriter,
+} from './validator-announce/validator-announce.js';

typescript/aleo-sdk/src/mailbox/mailbox-artifact-manager.ts

@@ -0,0 +1,70 @@
+import {
+  type ArtifactReader,
+  type ArtifactWriter,
+} from '@hyperlane-xyz/provider-sdk/artifact';
+import {
+  type DeployedMailboxAddress,
+  type IRawMailboxArtifactManager,
+  type MailboxType,
+  type RawMailboxArtifactConfigs,
+} from '@hyperlane-xyz/provider-sdk/mailbox';
+import { assert } from '@hyperlane-xyz/utils';
+
+import { type AnyAleoNetworkClient } from '../clients/base.js';
+import { type AleoSigner } from '../clients/signer.js';
+import { type AleoArtifactNetworkConfig } from '../utils/types.js';
+
+import { AleoMailboxReader, AleoMailboxWriter } from './mailbox.js';
+
+/**
+ * Aleo Mailbox Artifact Manager implementing IRawMailboxArtifactManager.
+ *
+ * This manager:
+ * - Provides factory methods for creating mailbox readers and writers
+ * - Handles mailbox deployment and configuration
+ */
+export class AleoMailboxArtifactManager implements IRawMailboxArtifactManager {
+  constructor(
+    private readonly config: AleoArtifactNetworkConfig,
+    private readonly aleoClient: AnyAleoNetworkClient,
+  ) {}
+
+  async readMailbox(address: string) {
+    const reader = this.createReader('mailbox');
+    return reader.read(address);
+  }
+
+  createReader<T extends MailboxType>(
+    type: T,
+  ): ArtifactReader<RawMailboxArtifactConfigs[T], DeployedMailboxAddress> {
+    const readers: {
+      [K in MailboxType]: () => ArtifactReader<
+        RawMailboxArtifactConfigs[K],
+        DeployedMailboxAddress
+      >;
+    } = {
+      mailbox: () => new AleoMailboxReader(this.aleoClient),
+    };
+
+    assert(readers[type], `Mailbox reader for ${type} not found`);
+    return readers[type]();
+  }
+
+  createWriter<T extends MailboxType>(
+    type: T,
+    signer: AleoSigner,
+  ): ArtifactWriter<RawMailboxArtifactConfigs[T], DeployedMailboxAddress> {
+    const writers: {
+      [K in MailboxType]: () => ArtifactWriter<
+        RawMailboxArtifactConfigs[K],
+        DeployedMailboxAddress
+      >;
+    } = {
+      mailbox: () =>
+        new AleoMailboxWriter(this.config, this.aleoClient, signer),
+    };
+
+    assert(writers[type], `Mailbox writer for ${type} not found`);
+    return writers[type]();
+  }
+}

typescript/aleo-sdk/src/mailbox/mailbox-query.ts

@@ -0,0 +1,67 @@
+import { assert } from '@hyperlane-xyz/utils';
+
+import { type AnyAleoNetworkClient } from '../clients/base.js';
+import { queryMappingValue } from '../utils/base-query.js';
+import {
+  formatHookAddress,
+  formatIsmAddress,
+  fromAleoAddress,
+} from '../utils/helper.js';
+import {
+  type AleoMailboxConfig,
+  type AleoMailboxData,
+} from '../utils/types.js';
+
+/**
+ * Query mailbox configuration from the chain.
+ *
+ * @param aleoClient - The Aleo network client
+ * @param mailboxAddress - The full mailbox address (e.g., "mailbox.aleo/aleo1...")
+ * @param onChainArtifactManagers - Artifact manager addresses (hookManagerAddress is ignored and derived from mailbox)
+ * @returns The mailbox configuration
+ */
+export async function getMailboxConfig(
+  aleoClient: AnyAleoNetworkClient,
+  mailboxAddress: string,
+): Promise<AleoMailboxConfig> {
+  const { programId: mailboxProgramId } = fromAleoAddress(mailboxAddress);
+  assert(
+    mailboxProgramId,
+    `Program Id is required for reading the on chain mailbox config. Is the input address formatted as "programId/address"?`,
+  );
+
+  const mailboxData = await queryMappingValue(
+    aleoClient,
+    mailboxProgramId,
+    'mailbox',
+    'true',
+    (raw): AleoMailboxData => {
+      const data = raw as AleoMailboxData | undefined;
+      assert(
+        data?.mailbox_owner,
+        `Invalid mailbox data structure for mailbox ${mailboxAddress}, expected object with mailbox_owner field`,
+      );
+      return data;
+    },
+  );
+
+  const imports = await aleoClient.getProgramImportNames(mailboxProgramId);
+  const ismManagerProgramId = imports.find((i) => i.includes('ism_manager'));
+  assert(
+    ismManagerProgramId,
+    `Expected to find ISM manager program id in mailbox program at ${mailboxAddress}`,
+  );
+
+  return {
+    address: mailboxAddress,
+    owner: mailboxData.mailbox_owner,
+    localDomain: mailboxData.local_domain,
+    nonce: mailboxData.nonce,
+    defaultIsm: formatIsmAddress(mailboxData.default_ism, ismManagerProgramId),
+    defaultHook: formatHookAddress(mailboxData.default_hook, mailboxProgramId),
+    requiredHook: formatHookAddress(
+      mailboxData.required_hook,
+      mailboxProgramId,
+    ),
+  };
+}