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

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 { spawnANT } from '../utils/ao.js';
-import { AOProcess } from './index.js';
+import { AoClient, AoMessageResult, AoSigner, ProcessConfiguration, UpgradeAntProgressEvent, WalletAddress, WithSigner, WriteOptions } from '../types/index.js';
+import { forkANT, spawnANT } from '../utils/ao.js';
+import { AOProcess, Logger } from './index.js';
 type ANTConfigOptionalStrict = Required<ProcessConfiguration> & {
     strict?: boolean;
     hyperbeamUrl?: string;
@@ -19,6 +19,42 @@ export declare class ANT {
      * Spawn a new ANT.
      */
     static spawn: typeof spawnANT;
+    /**
+     * Fork an ANT to a new process.
+     *
+     * @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.
+     *
+     * @param config
+     */
     static init(config: ANTConfigNoSigner): AoANTRead;
     static init(config: ANTConfigWithSigner): AoANTWrite;
 }
@@ -28,6 +64,8 @@ export declare class AoANTReadable implements AoANTRead {
     private strict;
     private hyperbeamUrl;
     private checkHyperBeamPromise;
+    private moduleId;
+    private moduleIdPromise;
     private logger;
     constructor(config: ANTConfigOptionalStrict);
     /**
@@ -42,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.
@@ -362,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/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> & {
-        antRegistryProcessId?: string;
+        antRegistryId?: 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 { 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;

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

@@ -30,6 +30,14 @@ 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, }: {
+    signer: AoSigner;
+    antProcessId: string;
+    logger?: Logger;
+    ao?: AoClient;
+    antRegistryId?: string;
+    onSigningProgress?: (name: keyof SpawnAntProgressEvent, payload: SpawnAntProgressEvent[keyof SpawnAntProgressEvent]) => void;
+}): Promise<string>;
 /**
  * @deprecated
  * Direct Evals are not encouraged when dealing with ANTs.

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';
 /**
- * @deprecated Use getArNSRecordsForAddress instead
+ * @beta This API is in beta and may change in the future.
  */
 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.1";

package/package.json

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