@ar.io/sdk 3.15.1 → 3.16.0-alpha.2

package/lib/esm/utils/ao.js

@@ -16,17 +16,45 @@
 import { ArconnectSigner, DataItem, createData } from '@dha-team/arbundles';
 import { connect, createDataItemSigner } from '@permaweb/aoconnect';
 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_LUA_ID, ANT_REGISTRY_ID, AOS_MODULE_ID, AO_AUTHORITY, DEFAULT_SCHEDULER_ID, } from '../constants.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';
-export async function spawnANT({ signer, module = AOS_MODULE_ID, ao = connect({
+export async function spawnANT({ signer, module, ao = connect({
     MODE: 'legacy',
-}), scheduler = DEFAULT_SCHEDULER_ID, state, antRegistryId = ANT_REGISTRY_ID, logger = Logger.default, authority = AO_AUTHORITY, }) {
+}), scheduler = DEFAULT_SCHEDULER_ID, state, antRegistryId = ANT_REGISTRY_ID, logger = Logger.default, authority = AO_AUTHORITY, onSigningProgress = (name, payload) => {
+    logger.debug('Signing progress', { name, payload });
+}, }) {
     if (state) {
         parseSchemaResult(SpawnANTStateSchema, state);
     }
+    let version;
+    if (module === undefined) {
+        const antRegistry = ANTVersions.init({
+            process: new AOProcess({
+                processId: antRegistryId,
+                ao,
+                logger,
+            }),
+        });
+        const { moduleId: latestAntModule, version: latestVersion } = await antRegistry.getLatestANTVersion();
+        logger.debug('Spawning new ANT with latest module from ANT registry', {
+            moduleId: latestAntModule,
+            version,
+            antRegistryId,
+        });
+        module = latestAntModule;
+        version = latestVersion;
+    }
+    onSigningProgress?.('spawning-ant', {
+        moduleId: module,
+        antRegistryId,
+        version,
+        state,
+    });
     const processId = await ao.spawn({
         module,
         scheduler,
@@ -44,64 +72,150 @@ export async function spawnANT({ signer, module = AOS_MODULE_ID, ao = connect({
             },
         ],
     });
-    let bootRes;
-    let attempts = 0;
-    while (attempts < 5 && bootRes === undefined) {
-        try {
-            if (bootRes === undefined) {
-                bootRes = await ao.result({
-                    process: processId,
-                    message: processId,
+    /**
+     * Note: if we are given a state, ensure the ANT was initialized with it
+     * there is a bug in the ANT source where we try to parse the empty default
+     * 'Data' string as JSON that causes the Invalid-Boot-Notice error, even though
+     * the ANT was initialized with the default state set by the ANT source code.
+     *
+     * Reference: https://github.com/ar-io/ar-io-ant-process/blob/b89018ffcce079add2e90e7ab82d0bbc9b671346/src/common/main.lua#L355-L358
+     */
+    if (state !== undefined) {
+        let bootRes;
+        let attempts = 0;
+        while (attempts < 5 && bootRes === undefined) {
+            try {
+                // TODO: could add a progress event here to show the boot progress and number of attempts
+                if (bootRes === undefined) {
+                    bootRes = await ao.result({
+                        process: processId,
+                        message: processId,
+                    });
+                }
+                break;
+            }
+            catch (error) {
+                logger.debug('Retrying ANT boot result fetch', {
+                    processId,
+                    module,
+                    scheduler,
+                    attempts,
+                    error,
                 });
+                attempts++;
+                await new Promise((resolve) => setTimeout(resolve, 1000 * attempts ** 2));
             }
-            break;
         }
-        catch (error) {
-            logger.debug('Retrying ANT boot result fetch', {
+        if (bootRes === undefined ||
+            bootRes.Messages?.some((m) => m?.Tags?.some((t) => t.value === 'Invalid-Boot-Notice'))) {
+            if (bootRes === undefined) {
+                throw new Error('Failed to get boot result');
+            }
+            const bootError = errorMessageFromOutput(bootRes);
+            logger.error('ANT failed to boot correctly', {
                 processId,
                 module,
                 scheduler,
-                attempts,
-                error,
+                bootRes,
+                bootError,
             });
-            attempts++;
-            await new Promise((resolve) => setTimeout(resolve, 1000 * attempts ** 2));
+            throw new Error(`ANT failed to boot correctly: ${bootError}`);
         }
     }
-    if (bootRes === undefined ||
-        bootRes.Messages?.some((m) => m?.Tags?.some((t) => t.value === 'Invalid-Boot-Notice'))) {
-        if (bootRes === undefined) {
-            // …
-            throw new Error('Failed to get boot result');
+    onSigningProgress?.('verifying-state', {
+        processId,
+        moduleId: module,
+        antRegistryId,
+    });
+    // Note: for hyperbeam caching, due to a SU issue, we need to send a second message to the ANT to cache the state
+    // We wait for the first message to be processed before sending the second one to ensure this is the second message
+    // We use the resulting state to check the owner of the ANT is set in the registry. Should this be patched on MUs,
+    // we can convert to just a simple dry-run to avoid sending/signing another message.
+    let owner;
+    try {
+        const processApi = new AOProcess({
+            processId,
+            ao,
+            logger,
+        });
+        const { id } = await processApi.send({
+            tags: [{ name: 'Action', value: 'State' }],
+            signer,
+        });
+        const stateResult = await ao.result({
+            process: processId,
+            message: id,
+        });
+        if (stateResult === undefined) {
+            throw new Error('Failed to get state result');
         }
-        const bootError = errorMessageFromOutput(bootRes);
-        logger.error('ANT failed to boot correctly', {
+        const { Owner } = JSON.parse(stateResult.Messages?.[0]?.Data ?? '{}');
+        owner = Owner;
+        logger.debug(`Successfully spawned new ANT and validated owner`, {
             processId,
             module,
-            scheduler,
-            bootRes,
-            bootError,
+            owner,
         });
-        throw new Error(`ANT failed to boot correctly: ${bootError}`);
     }
-    // for hyperbeam caching, due to a SU issue, we need to send a second message to the ANT to cache the state
-    // We wait for the first message to be processed before sending the second one to ensure this is the second message
-    const processApi = new AOProcess({
+    catch (error) {
+        logger.error('Failed to validate owner of spawned ANT', {
+            processId,
+            module,
+            error,
+        });
+        throw error;
+    }
+    /**
+     * Now confirm the owner of the ANT is set in the registry
+     * This is to ensure the ANT is available via the ANT registry
+     * for the owner to find and use the ANT.
+     */
+    if (owner === undefined) {
+        throw new Error(`Spawning ANT (${processId}) failed to set owner`);
+    }
+    onSigningProgress?.('registering-ant', {
         processId,
-        ao,
-        logger,
+        antRegistryId,
+        owner,
     });
-    await processApi.send({
-        tags: [{ name: 'Action', value: 'State' }],
+    // check the ACL for the owner
+    const antRegistry = ANTRegistry.init({
         signer,
+        processId: antRegistryId,
     });
-    logger.debug(`Spawned ANT`, {
-        processId,
-        module,
-        scheduler,
-    });
+    let attempts = 0;
+    const maxAttempts = 5;
+    while (attempts < maxAttempts) {
+        try {
+            const acl = await antRegistry.accessControlList({ address: owner });
+            if (acl === undefined) {
+                throw new Error('ACL not found for owner');
+            }
+            const { Owned } = acl;
+            if (!Owned.includes(processId)) {
+                throw new Error(`Spawned ANT (${processId}) not found in registry for owner ${owner}`);
+            }
+            return processId;
+        }
+        catch (error) {
+            logger.debug('Retrying ANT registry access control list fetch', {
+                owner,
+                antRegistryId,
+                attempts,
+                error,
+            });
+            attempts++;
+            await new Promise((resolve) => setTimeout(resolve, 1000 * attempts ** 2));
+        }
+    }
     return processId;
 }
+// TODO: add a utility for forking an ANT to the latest module that leverages getState and spawnANT
+/**
+ * @deprecated
+ * Direct Evals are not encouraged when dealing with ANTs.
+ * Instead, use spawnANT to fork an ANT to new module source code
+ */
 export async function evolveANT({ signer, processId, luaCodeTxId = ANT_LUA_ID, ao = connect({
     MODE: 'legacy',
 }), logger = Logger.default, arweave = defaultArweave, }) {
@@ -110,6 +224,7 @@ export async function evolveANT({ signer, processId, luaCodeTxId = ANT_LUA_ID, a
         ao,
         logger,
     });
+    logger.warn('Directly running an Eval on a process is not encouraged.');
     //TODO: cache locally and only fetch if not cached
     // We do not use arweave to get the data because it may throw on l2 tx data
     const { api: { host, port, protocol }, } = arweave.getConfig();

package/lib/esm/version.js

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

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

@@ -1,18 +1,3 @@
-/**
- * Copyright (C) 2022-2024 Permanent Data Solutions, Inc.
- *
- * Licensed under the Apache License, Version 2.0 (the "License");
- * you may not use this file except in compliance with the License.
- * You may obtain a copy of the License at
- *
- *     http://www.apache.org/licenses/LICENSE-2.0
- *
- * Unless required by applicable law or agreed to in writing, software
- * distributed under the License is distributed on an "AS IS" BASIS,
- * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
- * See the License for the specific language governing permissions and
- * limitations under the License.
- */
 import { AoArNSPurchaseParams, AoBuyRecordParams, AoExtendLeaseParams, AoIncreaseUndernameLimitParams } from '../../types/io.js';
 import { CLIWriteOptionsFromAoParams } from '../types.js';
 export declare function buyRecordCLICommand(o: CLIWriteOptionsFromAoParams<AoBuyRecordParams>): Promise<import("../../types/common.js").AoMessageResult>;

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

@@ -14,7 +14,7 @@ export declare function saveObservations(o: WriteActionCLIOptions & {
     failedGateways?: string[];
     transactionId?: string;
 }): Promise<import("../../types/common.js").AoMessageResult<Record<string, string | number | boolean | null>>>;
-export declare function increaseOperatorStake(o: OperatorStakeCLIOptions): Promise<import("../../types/common.js").WriteOptions>;
+export declare function increaseOperatorStake(o: OperatorStakeCLIOptions): Promise<import("../../types/common.js").AoMessageResult<Record<string, string | number | boolean | null>>>;
 export declare function decreaseOperatorStake(o: OperatorStakeCLIOptions): Promise<import("../../types/common.js").AoMessageResult<Record<string, string | number | boolean | null>>>;
 export declare function instantWithdrawal(o: AddressAndVaultIdCLIWriteOptions): Promise<import("../../types/common.js").AoMessageResult<Record<string, string | number | boolean | null>>>;
 export declare function cancelWithdrawal(o: AddressAndVaultIdCLIWriteOptions): Promise<import("../../types/common.js").AoMessageResult<Record<string, string | number | boolean | null>>>;

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

@@ -1,5 +1,6 @@
-import { AntReadOptions, AoANTHandler, AoANTInfo, AoANTRead, AoANTRecord, AoANTSetBaseNameRecordParams, AoANTSetUndernameRecordParams, AoANTState, AoANTVersionsRead, AoANTWrite, SortedANTRecords } from '../types/ant.js';
+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';
 type ANTConfigOptionalStrict = Required<ProcessConfiguration> & {
     strict?: boolean;
@@ -8,7 +9,16 @@ type ANTConfigOptionalStrict = Required<ProcessConfiguration> & {
 type ANTConfigNoSigner = ANTConfigOptionalStrict;
 type ANTConfigWithSigner = WithSigner<ANTConfigOptionalStrict>;
 export declare class ANT {
-    static versions: AoANTVersionsRead;
+    /**
+     * Versions of ANTs according to the ANT registry.
+     *
+     * Needs to be wrapped in a getter to avoid circular dependency issues.
+     */
+    static get versions(): import("../types/ant.js").AoANTVersionsRead;
+    /**
+     * Spawn a new ANT.
+     */
+    static spawn: typeof spawnANT;
     static init(config: ANTConfigNoSigner): AoANTRead;
     static init(config: ANTConfigWithSigner): AoANTWrite;
 }

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

@@ -1,6 +1,7 @@
 import Arweave from 'arweave';
-import { ARIOWithFaucet, AoARIORead, AoARIOWrite, AoAllDelegates, AoAllGatewayVaults, AoArNSNameData, AoArNSNameDataWithName, AoArNSPurchaseParams, AoArNSReservedNameData, AoArNSReservedNameDataWithName, AoBalanceWithAddress, AoBuyRecordParams, AoCreateVaultParams, AoDelegation, AoEligibleDistribution, AoEpochData, AoEpochDistributed, AoEpochDistributionData, AoEpochDistributionTotalsData, AoEpochObservationData, AoEpochSettings, AoExtendLeaseParams, AoExtendVaultParams, AoGateway, AoGatewayDelegateWithAddress, AoGatewayRegistrySettings, AoGatewayVault, AoGatewayWithAddress, AoGetCostDetailsParams, AoIncreaseUndernameLimitParams, AoIncreaseVaultParams, AoJoinNetworkParams, AoMessageResult, AoPaginatedAddressParams, AoPrimaryName, AoPrimaryNameRequest, AoRedelegationFeeInfo, AoRegistrationFees, AoReturnedName, AoRevokeVaultParams, AoTokenSupplyData, AoUpdateGatewaySettingsParams, AoVaultData, AoVaultedTransferParams, AoWalletVault, AoWeightedObserver, ArNSNameResolutionData, ArNSNameResolver, CostDetailsResult, DemandFactorSettings, EpochInput, OptionalArweave, OptionalPaymentUrl, PaginationParams, PaginationResult, ProcessConfiguration, TransactionId, WalletAddress, WithSigner, WriteOptions, mARIOToken } from '../types/index.js';
+import { ARIOWithFaucet, AoARIORead, AoARIOWrite, AoAllDelegates, AoAllGatewayVaults, AoArNSNameData, AoArNSNameDataWithName, AoArNSPurchaseParams, AoArNSReservedNameData, AoArNSReservedNameDataWithName, AoBalanceWithAddress, AoBuyRecordParams, AoCreateVaultParams, AoDelegation, AoEligibleDistribution, AoEpochData, AoEpochDistributed, AoEpochDistributionData, AoEpochDistributionTotalsData, AoEpochObservationData, AoEpochSettings, AoExtendLeaseParams, AoExtendVaultParams, AoGateway, AoGatewayDelegateWithAddress, AoGatewayRegistrySettings, AoGatewayVault, AoGatewayWithAddress, AoGetCostDetailsParams, AoIncreaseUndernameLimitParams, AoIncreaseVaultParams, AoJoinNetworkParams, AoMessageResult, AoPaginatedAddressParams, AoPrimaryName, AoPrimaryNameRequest, AoRedelegationFeeInfo, AoRegistrationFees, AoReturnedName, AoRevokeVaultParams, AoTokenSupplyData, AoUpdateGatewaySettingsParams, AoVaultData, AoVaultedTransferParams, AoWalletVault, AoWeightedObserver, ArNSNameResolutionData, ArNSNameResolver, CostDetailsResult, DemandFactorSettings, EpochInput, OptionalArweave, OptionalPaymentUrl, PaginationParams, PaginationResult, ProcessConfiguration, SpawnAntProgressEvent, TransactionId, WalletAddress, WithSigner, WriteOptions, mARIOToken } from '../types/index.js';
 import { AOProcess } from './contracts/ao-process.js';
+import { Logger } from './logger.js';
 import { TurboArNSPaymentProviderAuthenticated, TurboArNSPaymentProviderUnauthenticated } from './turbo.js';
 type ARIOConfigNoSigner = OptionalPaymentUrl<OptionalArweave<ProcessConfiguration>>;
 type ARIOConfigWithSigner = WithSigner<OptionalPaymentUrl<OptionalArweave<ProcessConfiguration>>>;
@@ -24,6 +25,7 @@ export declare class ARIOReadable implements AoARIORead, ArNSNameResolver {
     protected epochSettings: AoEpochSettings | undefined;
     protected arweave: Arweave;
     protected paymentProvider: TurboArNSPaymentProviderUnauthenticated;
+    protected logger: Logger;
     constructor(config?: ARIOConfigNoSigner);
     getInfo(): Promise<{
         Name: string;
@@ -187,7 +189,7 @@ export declare class ARIOWriteable extends ARIOReadable implements AoARIOWrite {
         reportTxId: TransactionId;
         failedGateways: WalletAddress[];
     }, options?: WriteOptions): Promise<AoMessageResult>;
-    buyRecord(params: AoBuyRecordParams, options?: WriteOptions): Promise<AoMessageResult>;
+    buyRecord(params: AoBuyRecordParams, options?: WriteOptions<keyof SpawnAntProgressEvent, SpawnAntProgressEvent[keyof SpawnAntProgressEvent]>): Promise<AoMessageResult>;
     /**
      * Upgrades an existing leased record to a permabuy.
      *

package/lib/types/constants.d.ts

@@ -25,7 +25,13 @@ export declare const ARIO_TESTNET_PROCESS_ID = "agYcCFJtrMG6cqMuZfskIkFTGvUPddIC
 export declare const ARIO_MAINNET_PROCESS_ID = "qNvAoz0TgcH7DMg8BCVn8jF32QH5L6T29VjHxhHqqGE";
 export declare const ANT_REGISTRY_ID = "i_le_yKKPVstLTDSmkHRqf-wYphMnwB9OhleiTgMkWc";
 export declare const MARIO_PER_ARIO = 1000000;
+/**
+ * @deprecated - use ANT.versions.getLatestANTVersion() to get latest ANT module
+ **/
 export declare const AOS_MODULE_ID = "nEjlSFA_8narJlVHApbczDPkMc9znSqYtqtf1iOdoxM";
+/**
+ * @deprecated - use ANT.versions.getLatestANTVersion() to get latest ANT module
+ **/
 export declare const ANT_LUA_ID = "sOW9Sdm1yoPRrzerC5iu1nsupp4e6I-HnJyYVHzvzQo";
 export declare const AO_AUTHORITY = "fcoN_xJeisVsPXA-trzVAuIiqO3ydLQxM-L4XbrQKzY";
 export declare const DEFAULT_SCHEDULER_ID = "_GQ33BkPtZrqxA84vM8Zk-N2aO0toNNu_C-l-rawrBA";

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

@@ -16,6 +16,7 @@
 import { ArconnectSigner, ArweaveSigner, EthereumSigner, InjectedEthereumSigner, Signer } from '@dha-team/arbundles';
 import { dryrun, message, monitor, result, results, spawn, unmonitor } from '@permaweb/aoconnect';
 import Arweave from 'arweave';
+import { SpawnANTState } from './ant.js';
 import { AoSigner } from './token.js';
 export type BlockHeight = number;
 export type SortKey = string;
@@ -41,11 +42,12 @@ export type ReadParameters<Input> = {
     functionName: string;
     inputs?: Input;
 };
-export type WriteOptions = {
+export type WriteOptions<K extends string = string, T = unknown> = {
     tags?: {
         name: string;
         value: string;
     }[];
+    onSigningProgress?: (name: K, payload: T) => void;
 };
 export type WriteParameters<Input> = WithSigner<Required<ReadParameters<Input>>>;
 export type AoMessageResult<T = Record<string, string | number | boolean | null>> = {
@@ -95,6 +97,24 @@ export interface AoClient {
     unmonitor: typeof unmonitor;
     dryrun: typeof dryrun;
 }
+export type SpawnAntProgressEvent = {
+    'spawning-ant': {
+        moduleId: string;
+        antRegistryId: string;
+        version: string | undefined;
+        state: SpawnANTState | undefined;
+    };
+    'verifying-state': {
+        processId: ProcessId;
+        moduleId: string;
+        antRegistryId: string;
+    };
+    'registering-ant': {
+        antRegistryId: string;
+        processId: ProcessId;
+        owner: WalletAddress;
+    };
+};
 export interface AOContract {
     read<K>({ tags, retries, }: {
         tags?: {

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

@@ -353,7 +353,7 @@ export type AoArNSPurchaseParams = AoArNSNameParams & {
 export type AoBuyRecordParams = AoArNSPurchaseParams & {
     years?: number;
     type: 'lease' | 'permabuy';
-    processId: string;
+    processId?: string;
 };
 export type AoExtendLeaseParams = AoArNSPurchaseParams & {
     years: number;

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

@@ -1,7 +1,7 @@
 import Arweave from 'arweave';
 import { Logger } from '../common/index.js';
 import { SpawnANTState } from '../types/ant.js';
-import { AoClient, AoEpochData, AoEpochDistributed, AoSigner, ContractSigner, WalletAddress } from '../types/index.js';
+import { AoClient, AoEpochData, AoEpochDistributed, AoSigner, ContractSigner, ProcessId, SpawnAntProgressEvent, WalletAddress } from '../types/index.js';
 export type SpawnANTParams = {
     signer: AoSigner;
     module?: string;
@@ -20,8 +20,17 @@ export type SpawnANTParams = {
      * @deprecated no longer in use due to compiled modules being preferred
      */
     arweave?: Arweave;
+    /**
+     * Callback function to be called when signing progress is made
+     */
+    onSigningProgress?: (name: keyof SpawnAntProgressEvent, payload: SpawnAntProgressEvent[keyof SpawnAntProgressEvent]) => void;
 };
-export declare function spawnANT({ signer, module, ao, scheduler, state, antRegistryId, logger, authority, }: SpawnANTParams): Promise<string>;
+export declare function spawnANT({ signer, module, ao, scheduler, state, antRegistryId, logger, authority, onSigningProgress, }: SpawnANTParams): Promise<ProcessId>;
+/**
+ * @deprecated
+ * Direct Evals are not encouraged when dealing with ANTs.
+ * Instead, use spawnANT to fork an ANT to new module source code
+ */
 export declare function evolveANT({ signer, processId, luaCodeTxId, ao, logger, arweave, }: {
     signer: AoSigner;
     processId: string;

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.15.0";
+export declare const version = "3.16.0-alpha.1";

package/package.json

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