@ar.io/sdk 3.18.3 → 3.19.0-alpha.10

package/lib/esm/cli/cli.js

@@ -19,12 +19,12 @@ import { program } from 'commander';
 import { AOProcess, spawnANT } from '../node/index.js';
 import { mARIOToken } from '../types/token.js';
 import { version } from '../version.js';
-import { setAntBaseNameCLICommand, setAntRecordCLICommand, } from './commands/antCommands.js';
+import { setAntBaseNameCLICommand, setAntRecordCLICommand, upgradeAntCLICommand, } from './commands/antCommands.js';
 import { buyRecordCLICommand, extendLeaseCLICommand, increaseUndernameLimitCLICommand, requestPrimaryNameCLICommand, setPrimaryNameCLICommand, upgradeRecordCLICommand, } from './commands/arnsPurchaseCommands.js';
 import { cancelWithdrawal, decreaseDelegateStake, decreaseOperatorStake, delegateStake, increaseOperatorStake, instantWithdrawal, joinNetwork, leaveNetwork, redelegateStake, saveObservations, updateGatewaySettings, } from './commands/gatewayWriteCommands.js';
 import { getAllGatewayVaults, getAllowedDelegates, getArNSRecord, getArNSReservedName, getArNSReturnedName, getCostDetails, getDelegations, getEpoch, getGateway, getGatewayDelegates, getGatewayVaults, getPrescribedNames, getPrescribedObservers, getPrimaryName, getTokenCost, getVault, listAllDelegatesCLICommand, listAntsForAddress, listArNSRecords, listArNSRecordsForAddress, listArNSReservedNames, listArNSReturnedNames, listGateways, resolveArNSName, } from './commands/readCommands.js';
 import { createVaultCLICommand, extendVaultCLICommand, increaseVaultCLICommand, revokeVaultCLICommand, transferCLICommand, vaultedTransferCLICommand, } from './commands/transfer.js';
-import { addressAndVaultIdOptions, antStateOptions, arnsPurchaseOptions, buyRecordOptions, decreaseDelegateStakeOptions, delegateStakeOptions, epochOptions, getVaultOptions, globalOptions, joinNetworkOptions, operatorStakeOptions, optionMap, paginationAddressOptions, paginationOptions, redelegateStakeOptions, setAntBaseNameOptions, setAntUndernameOptions, tokenCostOptions, transferOptions, updateGatewaySettingsOptions, vaultedTransferOptions, writeActionOptions, } from './options.js';
+import { addressAndVaultIdOptions, antStateOptions, arnsPurchaseOptions, buyRecordOptions, decreaseDelegateStakeOptions, delegateStakeOptions, epochOptions, getVaultOptions, globalOptions, joinNetworkOptions, operatorStakeOptions, optionMap, paginationAddressOptions, paginationOptions, redelegateStakeOptions, setAntBaseNameOptions, setAntUndernameOptions, tokenCostOptions, transferOptions, updateGatewaySettingsOptions, upgradeAntOptions, vaultedTransferOptions, writeActionOptions, } from './options.js';
 import { applyOptions, arioProcessIdFromOptions, assertConfirmationPrompt, customTagsFromOptions, epochInputFromOptions, formatARIOWithCommas, getANTStateFromOptions, getLoggerFromOptions, makeCommand, paginationParamsFromOptions, readANTFromOptions, readARIOFromOptions, requiredAddressFromOptions, requiredAoSignerFromOptions, requiredProcessIdFromOptions, requiredStringArrayFromOptions, requiredStringFromOptions, writeANTFromOptions, } from './utils.js';
 applyOptions(program
     .name('ar.io')
@@ -632,6 +632,12 @@ makeCommand({
     options: setAntUndernameOptions,
     action: setAntRecordCLICommand,
 });
+makeCommand({
+    name: 'upgrade-ant',
+    description: 'Upgrade an ANT by forking it to the latest version and reassigning names',
+    options: upgradeAntOptions,
+    action: upgradeAntCLICommand,
+});
 makeCommand({
     name: 'set-ant-ticker',
     description: 'Set the ticker of an ANT process',

package/lib/esm/cli/commands/antCommands.js

@@ -1,4 +1,4 @@
-import { assertConfirmationPrompt, customTagsFromOptions, defaultTtlSecondsCLI, requiredStringFromOptions, writeANTFromOptions, } from '../utils.js';
+import { arioProcessIdFromOptions, assertConfirmationPrompt, booleanFromOptions, customTagsFromOptions, defaultTtlSecondsCLI, readARIOFromOptions, requiredStringFromOptions, stringArrayFromOptions, writeANTFromOptions, } from '../utils.js';
 /** @deprecated -- use set-ant-base-name and set-ant-undername */
 export async function setAntRecordCLICommand(o) {
     const ttlSeconds = +(o.ttlSeconds ?? defaultTtlSecondsCLI);
@@ -40,3 +40,52 @@ export async function setAntUndernameCLICommand(o) {
         ttlSeconds,
     }, customTagsFromOptions(o));
 }
+export async function upgradeAntCLICommand(o) {
+    const writeAnt = writeANTFromOptions(o);
+    const arioProcessId = arioProcessIdFromOptions(o);
+    const ario = readARIOFromOptions(o);
+    const reassignAffiliatedNames = booleanFromOptions(o, 'reassignAffiliatedNames');
+    const names = stringArrayFromOptions(o, 'names') || [];
+    if (reassignAffiliatedNames) {
+        // Fetch all ArNS records that point to this ANT process
+        const allRecords = await ario.getArNSRecords({
+            filters: {
+                processId: writeAnt.processId,
+            },
+        });
+        // Filter records that belong to this ANT
+        const affiliatedNames = allRecords.items.map((record) => record.name);
+        names.push(...affiliatedNames);
+    }
+    if (names.length === 0) {
+        throw new Error('No names to reassign');
+    }
+    if (!o.skipConfirmation) {
+        await assertConfirmationPrompt(`Upgrade all names affiliated with this ANT on ARIO process?\n` +
+            `ARIO Process ID: ${arioProcessId}\n` +
+            `ANT Process ID: ${writeAnt.processId}\n` +
+            `Names that will be reassigned (${names.length}): ${names.join(', ')}`, o);
+    }
+    const result = reassignAffiliatedNames
+        ? await writeANTFromOptions(o).upgrade({
+            reassignAffiliatedNames,
+            arioProcessId,
+        })
+        : await writeANTFromOptions(o).upgrade({
+            names,
+            arioProcessId,
+        });
+    // Serialize error objects for JSON compatibility
+    const serializedFailedReassignedNames = {};
+    for (const [name, failure] of Object.entries(result.failedReassignedNames)) {
+        serializedFailedReassignedNames[name] = {
+            id: failure.id,
+            error: failure.error.message,
+        };
+    }
+    return {
+        forkedProcessId: result.forkedProcessId,
+        reassignedNames: result.reassignedNames,
+        failedReassignedNames: serializedFailedReassignedNames,
+    };
+}

package/lib/esm/cli/options.js

@@ -300,6 +300,11 @@ export const optionMap = {
         alias: '--referrer <referrer>',
         description: 'The referrer for ArNS purchase tracking',
     },
+    reassignAffiliatedNames: {
+        alias: '--reassign-affiliated-names',
+        description: 'Reassign all affiliated names to the new process',
+        type: 'boolean',
+    },
 };
 export const walletOptions = [
     optionMap.walletFile,
@@ -419,3 +424,9 @@ export const setAntUndernameOptions = [
     ...setAntBaseNameOptions,
     optionMap.undername,
 ];
+export const upgradeAntOptions = [
+    optionMap.processId,
+    optionMap.names,
+    optionMap.reassignAffiliatedNames,
+    ...writeActionOptions,
+];

package/lib/esm/cli/utils.js

@@ -18,7 +18,7 @@ import { connect } from '@permaweb/aoconnect';
 import { program } from 'commander';
 import { readFileSync } from 'fs';
 import prompts from 'prompts';
-import { ANT, ANTRegistry, ANT_REGISTRY_ID, AOProcess, ARIO, ARIOToken, ARIO_DEVNET_PROCESS_ID, ARIO_MAINNET_PROCESS_ID, ARIO_TESTNET_PROCESS_ID, ArweaveSigner, Logger, createAoSigner, fromB64Url, fundFromOptions, initANTStateForAddress, isValidFundFrom, isValidIntent, mARIOToken, sha256B64Url, validIntents, } from '../node/index.js';
+import { ANT, ANTRegistry, ANT_REGISTRY_ID, ANT_REGISTRY_TESTNET_ID, AOProcess, ARIO, ARIOToken, ARIO_DEVNET_PROCESS_ID, ARIO_MAINNET_PROCESS_ID, ARIO_TESTNET_PROCESS_ID, ArweaveSigner, Logger, createAoSigner, fromB64Url, fundFromOptions, initANTStateForAddress, isValidFundFrom, isValidIntent, mARIOToken, sha256B64Url, validIntents, } from '../node/index.js';
 import { globalOptions } from './options.js';
 export const defaultTtlSecondsCLI = 3600;
 export function stringifyJsonForCLIDisplay(json) {
@@ -78,6 +78,15 @@ export function arioProcessIdFromOptions({ arioProcessId, devnet, testnet, }) {
     }
     return ARIO_MAINNET_PROCESS_ID;
 }
+export function antRegistryIdFromOptions({ antRegistryProcessId, testnet, }) {
+    if (antRegistryProcessId !== undefined) {
+        return antRegistryProcessId;
+    }
+    if (testnet) {
+        return ANT_REGISTRY_TESTNET_ID;
+    }
+    return ANT_REGISTRY_ID;
+}
 function walletFromOptions({ privateKey, walletFile, }) {
     if (privateKey !== undefined) {
         return JSON.parse(privateKey);
@@ -125,18 +134,9 @@ export function readARIOFromOptions(options) {
         paymentUrl: options.paymentUrl,
     });
 }
-export function ANTRegistryProcessFromOptions(options) {
-    return new AOProcess({
-        processId: options.antRegistryProcessId ?? ANT_REGISTRY_ID,
-        ao: connect({
-            MODE: 'legacy',
-            CU_URL: options.cuUrl,
-        }),
-    });
-}
 export function readANTRegistryFromOptions(options) {
     return ANTRegistry.init({
-        process: ANTRegistryProcessFromOptions(options),
+        process: aoProcessFromOptions(options),
         hyperbeamUrl: options.hyperbeamUrl,
     });
 }

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, spawnANT } from '../utils/ao.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.
@@ -34,7 +36,155 @@ export class ANT {
      * Spawn a new ANT.
      */
     static spawn = spawnANT;
-    // implementation
+    /**
+     * Fork an ANT to a new process.
+     *
+     * @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, names, arioProcessId = ARIO_MAINNET_PROCESS_ID, antRegistryId = ANT_REGISTRY_ID, ao, logger = Logger.default, skipVersionCheck = false, onSigningProgress, hyperbeamUrl, }) {
+        // run time check if names is not empty but reassignAffiliatedNames it true, throw
+        if (names !== undefined &&
+            names.length > 0 &&
+            reassignAffiliatedNames !== undefined &&
+            reassignAffiliatedNames !== false) {
+            throw new Error('Cannot reassign all affiliated names and provide specific names');
+        }
+        let namesToReassign = names !== undefined && names.length > 0 ? new Set(names) : new Set();
+        // use reassignAffiliatedNames if names is empty
+        const shouldReassignAll = names === undefined || names.length === 0
+            ? (reassignAffiliatedNames ?? true)
+            : false;
+        const ario = ARIO.init({
+            process: new AOProcess({ processId: arioProcessId, ao }),
+        });
+        const getAllAffiliatedNames = async () => {
+            let cursor = undefined;
+            let hasMore = true;
+            const affiliatedNames = new Set();
+            while (hasMore) {
+                const page = await ario.getArNSRecords({
+                    filters: { processId: antProcessId },
+                    cursor,
+                    limit: 100,
+                });
+                page.items.forEach((r) => {
+                    affiliatedNames.add(r.name);
+                });
+                cursor = page.nextCursor;
+                hasMore = page.hasMore;
+            }
+            return affiliatedNames;
+        };
+        // get all the affiliated names if reassign all affiliated names is true
+        if (shouldReassignAll) {
+            onSigningProgress?.('fetching-affiliated-names', {
+                arioProcessId,
+                antProcessId,
+            });
+            namesToReassign = await getAllAffiliatedNames();
+        }
+        else {
+            if (names === undefined || names.length === 0) {
+                throw new Error('Names are required when reassignAffiliatedNames is false.');
+            }
+            onSigningProgress?.('validating-names', {
+                arioProcessId,
+                antProcessId,
+                names,
+            });
+            // confirm all names are affiliated with the ANT
+            const allAffiliatedNames = await getAllAffiliatedNames();
+            if (!names.every((name) => allAffiliatedNames.has(name))) {
+                // find any that are not affiliated with the ANT
+                const notAffiliatedNames = names.filter((name) => !allAffiliatedNames.has(name));
+                throw new Error(`All names must be affiliated with the ANT on the provided ARIO process. The following names are not affiliated to this ANT: ${notAffiliatedNames.join(', ')}`);
+            }
+        }
+        // if names is empty and reassign all affiliated names is false, throw an error
+        if (namesToReassign.size === 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 namesToReassign) {
+            let reassignmentResult;
+            try {
+                onSigningProgress?.('reassigning-name', {
+                    name,
+                    arioProcessId,
+                    antProcessId: forkedProcessId,
+                });
+                reassignmentResult = await existingAntProcess.reassignName({
+                    name,
+                    arioProcessId,
+                    antProcessId: forkedProcessId,
+                });
+                onSigningProgress?.('successfully-reassigned-name', {
+                    name,
+                    arioProcessId,
+                    antProcessId: forkedProcessId,
+                });
+                reassignedNames[name] = reassignmentResult;
+            }
+            catch (error) {
+                logger.error(`Failed to reassign name ${name}:`, { error });
+                onSigningProgress?.('failed-to-reassign-name', {
+                    name,
+                    arioProcessId,
+                    antProcessId: forkedProcessId,
+                    error,
+                });
+                // Continue with other names rather than failing completely
+                failedReassignedNames[name] = {
+                    id: reassignmentResult?.id,
+                    error,
+                };
+            }
+        }
+        return { forkedProcessId, reassignedNames, failedReassignedNames };
+    }
     static init(config) {
         if (config !== undefined && 'signer' in config) {
             return new AoANTWriteable(config);
@@ -45,9 +195,11 @@ export class ANT {
 export class AoANTReadable {
     process;
     processId;
-    strict;
     hyperbeamUrl;
+    strict;
     checkHyperBeamPromise;
+    moduleId;
+    moduleIdPromise;
     logger = Logger.default;
     constructor(config) {
         this.strict = config.strict || false;
@@ -180,6 +332,185 @@ 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',
+                    },
+                    signal: AbortSignal.timeout(10_000), // 10 second timeout
+                });
+                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.
@@ -711,4 +1042,60 @@ 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.
+     *
+     * 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(params) {
+        const { names, reassignAffiliatedNames, arioProcessId, antRegistryId, skipVersionCheck, onSigningProgress, } = params ?? {};
+        // Determine if we should reassign all names or specific names
+        const shouldReassignAll = names === undefined || names.length === 0
+            ? (reassignAffiliatedNames ?? true)
+            : false;
+        if (shouldReassignAll) {
+            return ANT.upgrade({
+                signer: this.signer,
+                antProcessId: this.processId,
+                ao: this.process.ao,
+                hyperbeamUrl: this.hyperbeamUrl?.toString(),
+                reassignAffiliatedNames: true,
+                arioProcessId: arioProcessId,
+                antRegistryId: antRegistryId,
+                onSigningProgress: onSigningProgress,
+                skipVersionCheck: skipVersionCheck,
+            });
+        }
+        else {
+            return ANT.upgrade({
+                signer: this.signer,
+                antProcessId: this.processId,
+                ao: this.process.ao,
+                hyperbeamUrl: this.hyperbeamUrl?.toString(),
+                names: names,
+                reassignAffiliatedNames: false,
+                arioProcessId: arioProcessId,
+                antRegistryId: antRegistryId,
+                onSigningProgress: onSigningProgress,
+                skipVersionCheck: 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/utils/ao.js

@@ -19,7 +19,7 @@ import { z } from 'zod';
 import { ANTRegistry } from '../common/ant-registry.js';
 import { ANTVersions } from '../common/ant-versions.js';
 import { defaultArweave } from '../common/arweave.js';
-import { AOProcess, Logger } from '../common/index.js';
+import { ANT, AOProcess, Logger } from '../common/index.js';
 import { ANT_LUA_ID, ANT_REGISTRY_ID, AO_AUTHORITY, DEFAULT_SCHEDULER_ID, } from '../constants.js';
 import { SpawnANTStateSchema } from '../types/ant.js';
 import { parseSchemaResult } from './schema.js';
@@ -211,7 +211,42 @@ export async function spawnANT({ signer, module, ao = connect({
     }
     return processId;
 }
-// TODO: add a utility for forking an ANT to the latest module that leverages getState and spawnANT
+export async function forkANT({ signer, antProcessId, logger = Logger.default, ao, moduleId, antRegistryId = ANT_REGISTRY_ID, onSigningProgress = (name, payload) => {
+    logger.debug('Forking ANT', { name, payload });
+}, }) {
+    // get the state of the current ANT and use it to spawn a new ANT
+    const ant = ANT.init({
+        process: new AOProcess({
+            processId: antProcessId,
+            ao,
+            logger,
+        }),
+    });
+    const state = await ant.getState();
+    if (state === undefined) {
+        throw new Error(`ANT state (${antProcessId}) is undefined and cannot be upgraded`);
+    }
+    const forkedProcessId = await spawnANT({
+        signer,
+        antRegistryId,
+        ao,
+        logger,
+        module: moduleId,
+        onSigningProgress,
+        state: {
+            owner: state.Owner,
+            name: state.Name,
+            ticker: state.Ticker,
+            description: state.Description,
+            keywords: state.Keywords,
+            controllers: state.Controllers,
+            records: state.Records,
+            balances: state.Balances,
+            logo: state.Logo,
+        },
+    });
+    return forkedProcessId;
+}
 /**
  * @deprecated
  * Direct Evals are not encouraged when dealing with ANTs.

package/lib/esm/version.js

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