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

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

@@ -296,6 +296,11 @@ export declare const optionMap: {
         alias: string;
         description: string;
     };
+    reassignAffiliatedNames: {
+        alias: string;
+        description: string;
+        type: string;
+    };
 };
 export declare const walletOptions: {
     alias: string;
@@ -390,3 +395,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,37 @@ 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, names, arioProcessId, antRegistryId, ao, logger, skipVersionCheck, onSigningProgress, hyperbeamUrl, }: {
+        signer: AoSigner;
+        antProcessId: string;
+        arioProcessId?: string;
+        skipVersionCheck?: boolean;
+        ao?: AoClient;
+        logger?: Logger;
+        antRegistryId?: string;
+        hyperbeamUrl?: string;
+        onSigningProgress?: (name: keyof UpgradeAntProgressEvent, payload: UpgradeAntProgressEvent[keyof UpgradeAntProgressEvent]) => void;
+    } & ({
+        names: string[];
+        reassignAffiliatedNames?: false;
+    } | {
+        names?: never;
+        reassignAffiliatedNames: true;
+    })): Promise<{
+        forkedProcessId: string;
+        reassignedNames: Record<string, AoMessageResult>;
+        failedReassignedNames: Record<string, {
+            id?: string;
+            error: Error;
+        }>;
+    }>;
     /**
      * Initialize overloads.
      *
@@ -36,9 +67,11 @@ export declare class ANT {
 export declare class AoANTReadable implements AoANTRead {
     protected process: AOProcess;
     readonly processId: string;
+    readonly hyperbeamUrl: URL | undefined;
     private strict;
-    private hyperbeamUrl;
     private checkHyperBeamPromise;
+    private moduleId;
+    private moduleIdPromise;
     private logger;
     constructor(config: ANTConfigOptionalStrict);
     /**
@@ -53,6 +86,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 +463,46 @@ 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.
+     *
+     * 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(params?: {
+        arioProcessId?: string;
+        antRegistryId?: string;
+        skipVersionCheck?: boolean;
+        onSigningProgress?: (name: keyof UpgradeAntProgressEvent, payload: UpgradeAntProgressEvent[keyof UpgradeAntProgressEvent]) => void;
+    } & ({
+        names: string[];
+        reassignAffiliatedNames?: false;
+    } | {
+        names?: never;
+        reassignAffiliatedNames?: true;
+    })): Promise<{
+        forkedProcessId: string;
+        reassignedNames: Record<string, AoMessageResult>;
+        failedReassignedNames: Record<string, {
+            id?: string;
+            error: Error;
+        }>;
+    }>;
 }
 export {};

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

@@ -155,7 +155,7 @@ export declare class ARIOReadable implements AoARIORead, ArNSNameResolver {
      * @returns {Promise<AoArNSNameData[]>} The ARNS names associated with the address
      */
     getArNSRecordsForAddress(params: PaginationParams<AoArNSNameDataWithName> & {
-        antRegistryId?: string;
+        antRegistryProcessId?: string;
         address: WalletAddress;
     }): Promise<PaginationResult<AoArNSNameDataWithName>>;
 }

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 { AoMessageResult, 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,25 @@ export interface AoANTWrite extends AoANTRead {
         arioProcessId: string;
         notifyOwners?: boolean;
     }>;
+    upgrade(params?: {
+        arioProcessId?: string;
+        antRegistryId?: string;
+        skipVersionCheck?: boolean;
+        onSigningProgress?: (name: keyof UpgradeAntProgressEvent, payload: UpgradeAntProgressEvent[keyof UpgradeAntProgressEvent]) => void;
+    } & ({
+        names: string[];
+        reassignAffiliatedNames?: false;
+    } | {
+        names?: never;
+        reassignAffiliatedNames?: true;
+    })): Promise<{
+        forkedProcessId: string;
+        reassignedNames: Record<string, AoMessageResult>;
+        failedReassignedNames: Record<string, {
+            id?: string;
+            error: Error;
+        }>;
+    }>;
 }
 export type AoANTSetBaseNameRecordParams = {
     transactionId: string;

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

@@ -126,6 +126,37 @@ 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;
+    };
+    'validating-names': {
+        arioProcessId: string;
+        antProcessId: string;
+        names: string[];
+    };
+    'failed-to-reassign-name': {
+        name: string;
+        arioProcessId: string;
+        antProcessId: string;
+        error?: Error;
+    };
+    'successfully-reassigned-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;

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

@@ -30,9 +30,10 @@ export type SpawnANTParams = {
     onSigningProgress?: (name: keyof SpawnAntProgressEvent, payload: SpawnAntProgressEvent[keyof SpawnAntProgressEvent]) => void;
 };
 export declare function spawnANT({ signer, module, ao, scheduler, state, tags, antRegistryId, logger, authority, onSigningProgress, }: SpawnANTParams): Promise<ProcessId>;
-export declare function forkANT({ signer, antProcessId, logger, ao, antRegistryId, onSigningProgress, }: {
+export declare function forkANT({ signer, antProcessId, logger, ao, moduleId, antRegistryId, onSigningProgress, }: {
     signer: AoSigner;
     antProcessId: string;
+    moduleId?: string;
     logger?: Logger;
     ao?: AoClient;
     antRegistryId?: string;

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

@@ -3,7 +3,7 @@ import { ILogger } from '../common/logger.js';
 import { AoANTRegistryRead } from '../types/ant-registry.js';
 import { AoARIORead, AoArNSNameData, AoClient, ProcessId, WalletAddress } from '../types/index.js';
 /**
- * @beta This API is in beta and may change in the future.
+ * @deprecated Use getArNSRecordsForAddress instead
  */
 export declare const getANTProcessesOwnedByWallet: ({ address, registry, }: {
     address: WalletAddress;

package/lib/types/version.d.ts

@@ -13,4 +13,4 @@
  * See the License for the specific language governing permissions and
  * limitations under the License.
  */
-export declare const version = "3.18.2";
+export declare const version = "3.19.0-alpha.9";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ar.io/sdk",
-  "version": "3.19.0-alpha.1",
+  "version": "3.19.0-alpha.10",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/ar-io/ar-io-sdk.git"