@ar.io/sdk 3.19.0-alpha.1 → 3.19.0-alpha.2

package/lib/esm/common/ant.js

@@ -14,13 +14,15 @@
  * limitations under the License.
  */
 import { z } from 'zod';
+import { ARIO_MAINNET_PROCESS_ID } from '../constants.js';
+import { ANT_REGISTRY_ID } from '../constants.js';
 import { AntBalancesSchema, AntControllersSchema, AntInfoSchema, AntRecordSchema, AntRecordsSchema, AntStateSchema, } from '../types/ant.js';
 import { isProcessConfiguration, isProcessIdConfiguration, } from '../types/index.js';
 import { convertHyperBeamStateToAoANTState, isHyperBeamANTState, sortANTRecords, } from '../utils/ant.js';
 import { createAoSigner, forkANT, spawnANT } from '../utils/ao.js';
 import { parseSchemaResult } from '../utils/schema.js';
 import { ANTVersions } from './ant-versions.js';
-import { AOProcess, InvalidContractConfigurationError, Logger, } from './index.js';
+import { AOProcess, ARIO, InvalidContractConfigurationError, Logger, } from './index.js';
 export class ANT {
     /**
      * Versions of ANTs according to the ANT registry.
@@ -40,6 +42,97 @@ export class ANT {
      * @param config
      */
     static fork = forkANT;
+    /**
+     * Upgrade an ANT by forking it to the latest version and reassigning names.
+     *
+     *
+     * @param config Configuration object for the upgrade process
+     * @returns Promise resolving to the forked process ID and successfully reassigned names
+     */
+    static async upgrade({ signer, antProcessId, reassignAffiliatedNames = true, // if true, will reassign all affiliated names, otherwise will use the names parameter
+    names = [], arioProcessId = ARIO_MAINNET_PROCESS_ID, antRegistryId = ANT_REGISTRY_ID, ao, logger = Logger.default, skipVersionCheck = false, onSigningProgress, hyperbeamUrl, }) {
+        // if names is not empty but reassignAffiliatedNames it true, throw
+        if (names.length > 0 && reassignAffiliatedNames) {
+            throw new Error('Cannot reassign all affiliated names and provide specific names');
+        }
+        // get all the affiliated names if reassign all affiliated names is true
+        if (reassignAffiliatedNames) {
+            const ario = ARIO.init({
+                process: new AOProcess({ processId: arioProcessId, ao }),
+            });
+            onSigningProgress?.('fetching-affiliated-names', {
+                arioProcessId,
+                antProcessId,
+            });
+            const allAffiliatedNames = await ario.getArNSRecords({
+                filters: {
+                    processId: antProcessId,
+                },
+            });
+            names.push(...allAffiliatedNames.items.map((record) => record.name));
+        }
+        // if names is empty and reassign all affiliated names is false, throw an error
+        if (names.length === 0) {
+            throw new Error('There are no names to reassign for this ANT.');
+        }
+        const existingAntProcess = ANT.init({
+            process: new AOProcess({
+                processId: antProcessId,
+                ao,
+                logger,
+            }),
+            hyperbeamUrl,
+            signer,
+        });
+        if (!skipVersionCheck) {
+            onSigningProgress?.('checking-version', {
+                antProcessId,
+                antRegistryId,
+            });
+            const isLatestVersion = await existingAntProcess.isLatestVersion({
+                antRegistryId,
+            });
+            if (isLatestVersion) {
+                return {
+                    forkedProcessId: antProcessId,
+                    reassignedNames: [],
+                    failedReassignedNames: [],
+                };
+            }
+        }
+        const forkedProcessId = await ANT.fork({
+            signer,
+            antProcessId,
+            ao,
+            logger,
+            antRegistryId,
+            onSigningProgress,
+        });
+        // we could parallelize this, but then signing progress would be harder to track
+        const reassignedNames = [];
+        const failedReassignedNames = [];
+        for (const name of names) {
+            try {
+                onSigningProgress?.('reassigning-name', {
+                    name,
+                    arioProcessId,
+                    antProcessId: forkedProcessId,
+                });
+                await existingAntProcess.reassignName({
+                    name,
+                    arioProcessId,
+                    antProcessId: forkedProcessId,
+                });
+                reassignedNames.push(name);
+            }
+            catch (error) {
+                logger.error(`Failed to reassign name ${name}:`, { error });
+                // Continue with other names rather than failing completely
+                failedReassignedNames.push(name);
+            }
+        }
+        return { forkedProcessId, reassignedNames, failedReassignedNames };
+    }
     static init(config) {
         if (config !== undefined && 'signer' in config) {
             return new AoANTWriteable(config);
@@ -53,6 +146,8 @@ export class AoANTReadable {
     strict;
     hyperbeamUrl;
     checkHyperBeamPromise;
+    moduleId;
+    moduleIdPromise;
     logger = Logger.default;
     constructor(config) {
         this.strict = config.strict || false;
@@ -185,6 +280,184 @@ export class AoANTReadable {
         const info = await this.getInfo();
         return info.Logo;
     }
+    /**
+     * Gets the module ID of the current ANT process by querying its spawn transaction tags.
+     * Results are cached after the first successful fetch.
+     *
+     * @param graphqlUrl The GraphQL endpoint URL (defaults to Arweave's GraphQL endpoint)
+     * @param retries Number of retry attempts (defaults to 3)
+     * @returns Promise<string> The module ID used to spawn this ANT process
+     * @example
+     * ```ts
+     * const moduleId = await ant.getModuleId();
+     * console.log(`ANT was spawned with module: ${moduleId}`);
+     * ```
+     */
+    async getModuleId({ 
+    // TODO: we could use wayfinder for this
+    graphqlUrl = 'https://arweave.net/graphql', retries = 3, } = {}) {
+        // Return cached result if available
+        if (this.moduleId !== undefined) {
+            this.logger.debug('Returning cached module ID', {
+                processId: this.processId,
+                moduleId: this.moduleId,
+            });
+            return this.moduleId;
+        }
+        // Return existing promise if already in flight
+        if (this.moduleIdPromise) {
+            this.logger.debug('Returning in-flight module ID promise', {
+                processId: this.processId,
+            });
+            return this.moduleIdPromise;
+        }
+        // Create and cache the promise to prevent multiple concurrent requests
+        this.moduleIdPromise = this.fetchModuleId({ graphqlUrl, retries });
+        try {
+            const moduleId = await this.moduleIdPromise;
+            this.moduleId = moduleId;
+            this.logger.debug('Successfully fetched and cached module ID', {
+                processId: this.processId,
+                moduleId,
+            });
+            return moduleId;
+        }
+        finally {
+            // Clear the promise so future calls can retry if this one failed
+            this.moduleIdPromise = undefined;
+        }
+    }
+    /**
+     * Internal method to fetch the module ID from GraphQL.
+     *
+     * TODO: this could be more like get process headers/metadata and fetch additional details.
+     *
+     * It seems like module is the only relevant one, but scheduler and authority are also available.
+     */
+    async fetchModuleId({ graphqlUrl, retries, }) {
+        const query = JSON.stringify({
+            query: `
+        query {
+          transactions(
+            ids: ["${this.processId}"]
+            first: 1,
+          ) {
+            edges {
+              node {
+                tags {
+                  name
+                  value
+                }
+              }
+            }
+          }
+        }
+      `,
+        });
+        for (let i = 0; i < retries; i++) {
+            try {
+                const response = await fetch(graphqlUrl, {
+                    method: 'POST',
+                    body: query,
+                    headers: {
+                        'Content-Type': 'application/json',
+                    },
+                });
+                if (!response.ok) {
+                    throw new Error(`GraphQL request failed: ${response.statusText}`);
+                }
+                const result = (await response.json());
+                if (result.errors) {
+                    throw new Error(`GraphQL errors: ${result.errors.map((e) => e.message).join(', ')}`);
+                }
+                const edges = result.data?.transactions?.edges;
+                if (!edges || edges.length === 0) {
+                    throw new Error(`No transaction found for process ID: ${this.processId}`);
+                }
+                const tags = edges[0].node.tags;
+                const moduleTag = tags.find((tag) => tag.name === 'Module');
+                if (!moduleTag) {
+                    throw new Error(`No Module tag found for process ID: ${this.processId}`);
+                }
+                return moduleTag.value;
+            }
+            catch (error) {
+                if (i === retries - 1) {
+                    // Final attempt failed
+                    this.logger.error('Failed to get ANT module ID after all retries:', {
+                        error,
+                    });
+                    throw new Error(`Unable to determine module ID for ANT process ${this.processId}: ${error.message}`);
+                }
+                // Exponential backoff
+                await new Promise((resolve) => setTimeout(resolve, Math.pow(2, i) * 1000));
+            }
+        }
+        throw new Error(`Unexpected error getting module ID for process ${this.processId}`);
+    }
+    /**
+     * Gets the version string of the current ANT by matching its module ID
+     * with versions from the ANT registry.
+     *
+     * @param antRegistryId The ANT registry process ID (defaults to mainnet registry)
+     * @param graphqlUrl The GraphQL endpoint URL for getModuleId (defaults to Arweave's GraphQL endpoint)
+     * @param retries Number of retry attempts for getModuleId (defaults to 3)
+     * @returns Promise<string> The version string (e.g., "1.0.15") or "unknown" if not found
+     * @example
+     * ```ts
+     * const version = await ant.getVersion();
+     * console.log(`ANT is running version: ${version}`);
+     * ```
+     */
+    async getVersion({ antRegistryId = ANT_REGISTRY_ID, graphqlUrl = 'https://arweave.net/graphql', retries = 3, } = {}) {
+        // Get the current ANT's module ID
+        const currentModuleId = await this.getModuleId({ graphqlUrl, retries });
+        // Get all versions from the ANT registry
+        const antVersions = ANTVersions.init({
+            processId: antRegistryId,
+        });
+        const versions = await antVersions.getANTVersions();
+        // Find the version that matches our module ID
+        for (const [version, versionInfo] of Object.entries(versions)) {
+            if (versionInfo.moduleId === currentModuleId) {
+                this.logger.debug('Found matching ANT version', {
+                    processId: this.processId,
+                    moduleId: currentModuleId,
+                    version,
+                });
+                return version;
+            }
+        }
+        const versionForModuleId = Object.entries(versions)
+            .map(([version, versionInfo]) => ({
+            version,
+            ...versionInfo,
+        }))
+            .find((obj) => obj.moduleId === currentModuleId);
+        return versionForModuleId?.version ?? 'unknown';
+    }
+    /**
+     * Checks if the current ANT version is the latest according to the ANT registry.
+     *
+     * @param antRegistryId Optional ANT registry process ID. Defaults to mainnet ANT registry.
+     * @param graphqlUrl Optional GraphQL endpoint. Defaults to https://arweave.net/graphql.
+     * @param retries Optional number of retries for fetching module ID. Defaults to 3.
+     * @returns {Promise<boolean>} True if current ANT version is the latest, false otherwise.
+     */
+    async isLatestVersion({ antRegistryId = ANT_REGISTRY_ID, graphqlUrl = 'https://arweave.net/graphql', retries = 3, } = {}) {
+        // Get the current ANT's version
+        const currentVersion = await this.getVersion({
+            antRegistryId,
+            graphqlUrl,
+            retries,
+        });
+        // Get all versions from the ANT registry
+        const antVersions = ANTVersions.init({
+            processId: antRegistryId,
+        });
+        const latestVersion = await antVersions.getLatestANTVersion();
+        return currentVersion === latestVersion.version;
+    }
     /**
      * @param undername @type {string} The domain name.
      * @returns {Promise<ANTRecord>} The record of the undername domain.
@@ -716,4 +989,40 @@ export class AoANTWriteable extends AoANTReadable {
             signer: this.signer,
         });
     }
+    /**
+     * Upgrade this ANT by forking it to the latest version and reassigning names.
+     *
+     * This is a convenience method that calls the static ANT.upgrade() method
+     * using this instance's process ID and signer.
+     *
+     * TODO: Add version checking by implementing a getVersion API on ANTs to compare
+     * current version with latest ANT registry version and skip if already up to date.
+     *
+     * @param names @type {string[]} The ArNS names to reassign to the upgraded ANT.
+     * @param arioProcessId @type {string} The processId of the ARIO contract.
+     * @param antRegistryId @type {string} Optional ANT registry ID.
+     * @param onSigningProgress Progress callback function.
+     * @returns {Promise} The upgrade results.
+     * @example
+     * ```ts
+     * const result = await ant.upgrade({
+     *   names: ["example", "test"],
+     *   arioProcessId: ARIO_MAINNET_PROCESS_ID
+     * });
+     * console.log(`Upgraded to process: ${result.forkedProcessId}`);
+     * ```
+     */
+    async upgrade({ names, reassignAffiliatedNames, arioProcessId, antRegistryId, onSigningProgress, skipVersionCheck = false, }) {
+        return ANT.upgrade({
+            signer: this.signer,
+            antProcessId: this.processId,
+            ao: this.process.ao,
+            names,
+            reassignAffiliatedNames,
+            arioProcessId,
+            antRegistryId,
+            onSigningProgress,
+            skipVersionCheck,
+        });
+    }
 }

package/lib/esm/constants.js

@@ -21,6 +21,7 @@ export const ARIO_DEVNET_PROCESS_ID = 'GaQrvEMKBpkjofgnBi_B3IgIDmY_XYelVLB6GcRGr
 export const arioDevnetProcessId = ARIO_DEVNET_PROCESS_ID;
 export const ARIO_TESTNET_PROCESS_ID = 'agYcCFJtrMG6cqMuZfskIkFTGvUPddICmtQSBIoPdiA';
 export const ARIO_MAINNET_PROCESS_ID = 'qNvAoz0TgcH7DMg8BCVn8jF32QH5L6T29VjHxhHqqGE';
+export const ANT_REGISTRY_TESTNET_ID = 'RR0vheYqtsKuJCWh6xj0beE35tjaEug5cejMw9n2aa8';
 export const ANT_REGISTRY_ID = 'i_le_yKKPVstLTDSmkHRqf-wYphMnwB9OhleiTgMkWc';
 export const MARIO_PER_ARIO = 1_000_000;
 /**

package/lib/esm/utils/ant.js

@@ -37,6 +37,9 @@ export const sortANTRecords = (antRecords) => {
     // now that they are sorted, add the index to each record - this is their position in the sorted list and is used to enforce undername limits
     return Object.fromEntries(sortedEntries.map(([a, aRecord], index) => [a, { ...aRecord, index }]));
 };
+/**
+ * @deprecated - this is no longer necessary because HyperBeam now uses the AoANTState type
+ */
 export const isHyperBeamANTState = (state) => {
     return ('name' in state &&
         'ticker' in state &&
@@ -54,6 +57,7 @@ export const isHyperBeamANTState = (state) => {
 /**
  * Convert HyperBeam serialized ANT state to backwards compatible format.
  *
+ * @deprecated - this is no longer necessary because HyperBeam now uses the AOANTState type
  * @param state - The HyperBeam serialized ANT state.
  */
 export const convertHyperBeamStateToAoANTState = (initialState) => {

package/lib/esm/version.js

@@ -14,4 +14,4 @@
  * limitations under the License.
  */
 // AUTOMATICALLY GENERATED FILE - DO NOT TOUCH
-export const version = '3.19.0-alpha.1';
+export const version = '3.19.0-alpha.2';

package/lib/types/cli/commands/antCommands.d.ts

@@ -19,3 +19,8 @@ import { CLIWriteOptionsFromAoAntParams } from '../types.js';
 export declare function setAntRecordCLICommand(o: CLIWriteOptionsFromAoAntParams<AoANTSetUndernameRecordParams>): Promise<import("../../types/common.js").AoMessageResult<Record<string, string | number | boolean | null>>>;
 export declare function setAntBaseNameCLICommand(o: CLIWriteOptionsFromAoAntParams<AoANTSetBaseNameRecordParams>): Promise<import("../../types/common.js").AoMessageResult<Record<string, string | number | boolean | null>>>;
 export declare function setAntUndernameCLICommand(o: CLIWriteOptionsFromAoAntParams<AoANTSetUndernameRecordParams>): Promise<import("../../types/common.js").AoMessageResult<Record<string, string | number | boolean | null>>>;
+export declare function upgradeAntCLICommand(o: CLIWriteOptionsFromAoAntParams<Record<string, unknown>>): Promise<{
+    forkedProcessId: string;
+    reassignedNames: string[];
+    failedReassignedNames: string[];
+}>;

package/lib/types/cli/options.d.ts

@@ -390,3 +390,7 @@ export declare const setAntUndernameOptions: {
     alias: string;
     description: string;
 }[];
+export declare const upgradeAntOptions: {
+    alias: string;
+    description: string;
+}[];

package/lib/types/cli/utils.d.ts

@@ -1,6 +1,6 @@
 import { JWKInterface } from 'arweave/node/lib/wallet.js';
 import { Command, OptionValues } from 'commander';
-import { AOProcess, ARIOToken, AoANTRead, AoANTRegistryRead, AoANTWrite, AoARIORead, AoARIOWrite, AoGetCostDetailsParams, AoRedelegateStakeParams, AoSigner, AoUpdateGatewaySettingsParams, ContractSigner, EpochInput, FundFrom, Logger, PaginationParams, SpawnANTState, WriteOptions, mARIOToken } from '../node/index.js';
+import { ARIOToken, AoANTRead, AoANTRegistryRead, AoANTWrite, AoARIORead, AoARIOWrite, AoGetCostDetailsParams, AoRedelegateStakeParams, AoSigner, AoUpdateGatewaySettingsParams, ContractSigner, EpochInput, FundFrom, Logger, PaginationParams, SpawnANTState, WriteOptions, mARIOToken } from '../node/index.js';
 import { ANTStateCLIOptions, AddressCLIOptions, EpochCLIOptions, GetTokenCostCLIOptions, GlobalCLIOptions, InitiatorCLIOptions, JsonSerializable, PaginationCLIOptions, ProcessIdCLIOptions, RedelegateStakeCLIOptions, TransferCLIOptions, UpdateGatewaySettingsCLIOptions, WalletCLIOptions, WriteActionCLIOptions } from './types.js';
 export declare const defaultTtlSecondsCLI = 3600;
 export declare function stringifyJsonForCLIDisplay(json: JsonSerializable | unknown): string;
@@ -18,11 +18,11 @@ export declare function makeCommand<O extends OptionValues = GlobalCLIOptions>({
     options?: CommanderOption[];
 }): Command;
 export declare function arioProcessIdFromOptions({ arioProcessId, devnet, testnet, }: GlobalCLIOptions): string;
+export declare function antRegistryIdFromOptions({ antRegistryProcessId, testnet, }: GlobalCLIOptions): string;
 export declare function requiredJwkFromOptions(options: WalletCLIOptions): JWKInterface;
 export declare function jwkToAddress(jwk: JWKInterface): string;
 export declare function getLoggerFromOptions(options: GlobalCLIOptions): Logger;
 export declare function readARIOFromOptions(options: GlobalCLIOptions): AoARIORead;
-export declare function ANTRegistryProcessFromOptions(options: ProcessIdCLIOptions): AOProcess;
 export declare function readANTRegistryFromOptions(options: ProcessIdCLIOptions): AoANTRegistryRead;
 export declare function contractSignerFromOptions(options: WalletCLIOptions): {
     signer: ContractSigner;

package/lib/types/common/ant.d.ts

@@ -1,7 +1,7 @@
 import { AntReadOptions, AoANTHandler, AoANTInfo, AoANTRead, AoANTRecord, AoANTSetBaseNameRecordParams, AoANTSetUndernameRecordParams, AoANTState, AoANTWrite, SortedANTRecords } from '../types/ant.js';
-import { AoMessageResult, ProcessConfiguration, WalletAddress, WithSigner, WriteOptions } from '../types/index.js';
+import { AoClient, AoMessageResult, AoSigner, ProcessConfiguration, UpgradeAntProgressEvent, WalletAddress, WithSigner, WriteOptions } from '../types/index.js';
 import { forkANT, spawnANT } from '../utils/ao.js';
-import { AOProcess } from './index.js';
+import { AOProcess, Logger } from './index.js';
 type ANTConfigOptionalStrict = Required<ProcessConfiguration> & {
     strict?: boolean;
     hyperbeamUrl?: string;
@@ -25,6 +25,31 @@ export declare class ANT {
      * @param config
      */
     static fork: typeof forkANT;
+    /**
+     * Upgrade an ANT by forking it to the latest version and reassigning names.
+     *
+     *
+     * @param config Configuration object for the upgrade process
+     * @returns Promise resolving to the forked process ID and successfully reassigned names
+     */
+    static upgrade({ signer, antProcessId, reassignAffiliatedNames, // if true, will reassign all affiliated names, otherwise will use the names parameter
+    names, arioProcessId, antRegistryId, ao, logger, skipVersionCheck, onSigningProgress, hyperbeamUrl, }: {
+        signer: AoSigner;
+        antProcessId: string;
+        names?: string[];
+        reassignAffiliatedNames?: boolean;
+        arioProcessId?: string;
+        skipVersionCheck?: boolean;
+        ao?: AoClient;
+        logger?: Logger;
+        antRegistryId?: string;
+        hyperbeamUrl?: string;
+        onSigningProgress?: (name: keyof UpgradeAntProgressEvent, payload: UpgradeAntProgressEvent[keyof UpgradeAntProgressEvent]) => void;
+    }): Promise<{
+        forkedProcessId: string;
+        reassignedNames: string[];
+        failedReassignedNames: string[];
+    }>;
     /**
      * Initialize overloads.
      *
@@ -39,6 +64,8 @@ export declare class AoANTReadable implements AoANTRead {
     private strict;
     private hyperbeamUrl;
     private checkHyperBeamPromise;
+    private moduleId;
+    private moduleIdPromise;
     private logger;
     constructor(config: ANTConfigOptionalStrict);
     /**
@@ -53,6 +80,63 @@ export declare class AoANTReadable implements AoANTRead {
      * Returns the TX ID of the logo set for the ANT.
      */
     getLogo(): Promise<string>;
+    /**
+     * Gets the module ID of the current ANT process by querying its spawn transaction tags.
+     * Results are cached after the first successful fetch.
+     *
+     * @param graphqlUrl The GraphQL endpoint URL (defaults to Arweave's GraphQL endpoint)
+     * @param retries Number of retry attempts (defaults to 3)
+     * @returns Promise<string> The module ID used to spawn this ANT process
+     * @example
+     * ```ts
+     * const moduleId = await ant.getModuleId();
+     * console.log(`ANT was spawned with module: ${moduleId}`);
+     * ```
+     */
+    getModuleId({ graphqlUrl, retries, }?: {
+        graphqlUrl?: string;
+        retries?: number;
+    }): Promise<string>;
+    /**
+     * Internal method to fetch the module ID from GraphQL.
+     *
+     * TODO: this could be more like get process headers/metadata and fetch additional details.
+     *
+     * It seems like module is the only relevant one, but scheduler and authority are also available.
+     */
+    private fetchModuleId;
+    /**
+     * Gets the version string of the current ANT by matching its module ID
+     * with versions from the ANT registry.
+     *
+     * @param antRegistryId The ANT registry process ID (defaults to mainnet registry)
+     * @param graphqlUrl The GraphQL endpoint URL for getModuleId (defaults to Arweave's GraphQL endpoint)
+     * @param retries Number of retry attempts for getModuleId (defaults to 3)
+     * @returns Promise<string> The version string (e.g., "1.0.15") or "unknown" if not found
+     * @example
+     * ```ts
+     * const version = await ant.getVersion();
+     * console.log(`ANT is running version: ${version}`);
+     * ```
+     */
+    getVersion({ antRegistryId, graphqlUrl, retries, }?: {
+        antRegistryId?: string;
+        graphqlUrl?: string;
+        retries?: number;
+    }): Promise<string>;
+    /**
+     * Checks if the current ANT version is the latest according to the ANT registry.
+     *
+     * @param antRegistryId Optional ANT registry process ID. Defaults to mainnet ANT registry.
+     * @param graphqlUrl Optional GraphQL endpoint. Defaults to https://arweave.net/graphql.
+     * @param retries Optional number of retries for fetching module ID. Defaults to 3.
+     * @returns {Promise<boolean>} True if current ANT version is the latest, false otherwise.
+     */
+    isLatestVersion({ antRegistryId, graphqlUrl, retries, }?: {
+        antRegistryId?: string;
+        graphqlUrl?: string;
+        retries?: number;
+    }): Promise<boolean>;
     /**
      * @param undername @type {string} The domain name.
      * @returns {Promise<ANTRecord>} The record of the undername domain.
@@ -373,5 +457,40 @@ export declare class AoANTWriteable extends AoANTReadable implements AoANTWrite
         arioProcessId: string;
         notifyOwners?: boolean;
     }, options?: WriteOptions): Promise<AoMessageResult>;
+    /**
+     * Upgrade this ANT by forking it to the latest version and reassigning names.
+     *
+     * This is a convenience method that calls the static ANT.upgrade() method
+     * using this instance's process ID and signer.
+     *
+     * TODO: Add version checking by implementing a getVersion API on ANTs to compare
+     * current version with latest ANT registry version and skip if already up to date.
+     *
+     * @param names @type {string[]} The ArNS names to reassign to the upgraded ANT.
+     * @param arioProcessId @type {string} The processId of the ARIO contract.
+     * @param antRegistryId @type {string} Optional ANT registry ID.
+     * @param onSigningProgress Progress callback function.
+     * @returns {Promise} The upgrade results.
+     * @example
+     * ```ts
+     * const result = await ant.upgrade({
+     *   names: ["example", "test"],
+     *   arioProcessId: ARIO_MAINNET_PROCESS_ID
+     * });
+     * console.log(`Upgraded to process: ${result.forkedProcessId}`);
+     * ```
+     */
+    upgrade({ names, reassignAffiliatedNames, arioProcessId, antRegistryId, onSigningProgress, skipVersionCheck, }: {
+        names?: string[];
+        arioProcessId?: string;
+        antRegistryId?: string;
+        skipVersionCheck?: boolean;
+        reassignAffiliatedNames?: boolean;
+        onSigningProgress?: (name: keyof UpgradeAntProgressEvent, payload: UpgradeAntProgressEvent[keyof UpgradeAntProgressEvent]) => void;
+    }): Promise<{
+        forkedProcessId: string;
+        reassignedNames: string[];
+        failedReassignedNames: string[];
+    }>;
 }
 export {};

package/lib/types/constants.d.ts

@@ -20,6 +20,7 @@ export declare const ARIO_DEVNET_PROCESS_ID = "GaQrvEMKBpkjofgnBi_B3IgIDmY_XYelV
 export declare const arioDevnetProcessId = "GaQrvEMKBpkjofgnBi_B3IgIDmY_XYelVLB6GcRGrHc";
 export declare const ARIO_TESTNET_PROCESS_ID = "agYcCFJtrMG6cqMuZfskIkFTGvUPddICmtQSBIoPdiA";
 export declare const ARIO_MAINNET_PROCESS_ID = "qNvAoz0TgcH7DMg8BCVn8jF32QH5L6T29VjHxhHqqGE";
+export declare const ANT_REGISTRY_TESTNET_ID = "RR0vheYqtsKuJCWh6xj0beE35tjaEug5cejMw9n2aa8";
 export declare const ANT_REGISTRY_ID = "i_le_yKKPVstLTDSmkHRqf-wYphMnwB9OhleiTgMkWc";
 export declare const MARIO_PER_ARIO = 1000000;
 /**

package/lib/types/types/ant.d.ts

@@ -14,7 +14,7 @@
  * limitations under the License.
  */
 import { z } from 'zod';
-import { AoWriteAction, WalletAddress } from './common.js';
+import { AoWriteAction, UpgradeAntProgressEvent, WalletAddress } from './common.js';
 /**
  * example error:
  *  {
@@ -264,6 +264,20 @@ export interface AoANTRead {
     }, opts?: AntReadOptions): Promise<number>;
     getBalances(opts?: AntReadOptions): Promise<Record<WalletAddress, number>>;
     getHandlers(): Promise<AoANTHandler[]>;
+    getModuleId(opts?: {
+        graphqlUrl?: string;
+        retries?: number;
+    }): Promise<string>;
+    getVersion(opts?: {
+        antRegistryId?: string;
+        graphqlUrl?: string;
+        retries?: number;
+    }): Promise<string>;
+    isLatestVersion(opts?: {
+        antRegistryId?: string;
+        graphqlUrl?: string;
+        retries?: number;
+    }): Promise<boolean>;
 }
 export interface AoANTWrite extends AoANTRead {
     transfer: AoWriteAction<{
@@ -320,6 +334,17 @@ export interface AoANTWrite extends AoANTRead {
         arioProcessId: string;
         notifyOwners?: boolean;
     }>;
+    upgrade(params: {
+        names?: string[];
+        reassignAffiliatedNames?: boolean;
+        arioProcessId?: string;
+        antRegistryId?: string;
+        onSigningProgress?: (name: keyof UpgradeAntProgressEvent, payload: UpgradeAntProgressEvent[keyof UpgradeAntProgressEvent]) => void;
+    }): Promise<{
+        forkedProcessId: string;
+        reassignedNames: string[];
+        failedReassignedNames: string[];
+    }>;
 }
 export type AoANTSetBaseNameRecordParams = {
     transactionId: string;

package/lib/types/types/common.d.ts

@@ -126,6 +126,21 @@ export type SpawnAntProgressEvent = {
         owner: WalletAddress;
     };
 };
+export type UpgradeAntProgressEvent = SpawnAntProgressEvent & {
+    'checking-version': {
+        antProcessId: string;
+        antRegistryId: string;
+    };
+    'fetching-affiliated-names': {
+        arioProcessId: string;
+        antProcessId: string;
+    };
+    'reassigning-name': {
+        name: string;
+        arioProcessId: string;
+        antProcessId: string;
+    };
+};
 export type BuyArNSNameProgressEvents = SpawnAntProgressEvent & {
     'buying-name': AoBuyRecordParams;
 };

package/lib/types/utils/ant.d.ts

@@ -24,10 +24,14 @@ import { ANTRecords, AoANTState, HyperBeamANTState, SortedANTRecords } from '../
  * @param antRecords - The ANT records to sort.
  */
 export declare const sortANTRecords: (antRecords: ANTRecords) => SortedANTRecords;
+/**
+ * @deprecated - this is no longer necessary because HyperBeam now uses the AoANTState type
+ */
 export declare const isHyperBeamANTState: (state: any) => state is HyperBeamANTState;
 /**
  * Convert HyperBeam serialized ANT state to backwards compatible format.
  *
+ * @deprecated - this is no longer necessary because HyperBeam now uses the AOANTState type
  * @param state - The HyperBeam serialized ANT state.
  */
 export declare const convertHyperBeamStateToAoANTState: (initialState: HyperBeamANTState) => AoANTState;