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

package/lib/cjs/cli/cli.js

@@ -403,6 +403,7 @@ const utils_js_1 = require("./utils.js");
     options: options_js_1.buyRecordOptions,
     action: arnsPurchaseCommands_js_1.buyRecordCLICommand,
 });
+// TODO alias buy-record with buy-name
 (0, utils_js_1.makeCommand)({
     name: 'upgrade-record',
     description: 'Upgrade the lease of a record to a permabuy',

package/lib/cjs/cli/commands/arnsPurchaseCommands.js

@@ -5,6 +5,22 @@ exports.upgradeRecordCLICommand = upgradeRecordCLICommand;
 exports.extendLeaseCLICommand = extendLeaseCLICommand;
 exports.increaseUndernameLimitCLICommand = increaseUndernameLimitCLICommand;
 exports.requestPrimaryNameCLICommand = requestPrimaryNameCLICommand;
+/**
+ * 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.
+ */
+const ant_js_1 = require("../../common/ant.js");
 const utils_js_1 = require("../utils.js");
 async function buyRecordCLICommand(o) {
     const { ario, signerAddress } = (0, utils_js_1.writeARIOFromOptions)(o);
@@ -14,10 +30,6 @@ async function buyRecordCLICommand(o) {
     const fundFrom = (0, utils_js_1.fundFromFromOptions)(o);
     const referrer = (0, utils_js_1.referrerFromOptions)(o);
     const processId = o.processId;
-    if (processId === undefined) {
-        // TODO: Spawn ANT process, register it to ANT registry, get process ID
-        throw new Error('Process ID must be provided for buy-record');
-    }
     if (!o.skipConfirmation) {
         const existingRecord = await ario.getArNSRecord({
             name,
@@ -37,7 +49,13 @@ async function buyRecordCLICommand(o) {
                 fromAddress: signerAddress,
             },
         });
-        await (0, utils_js_1.assertConfirmationPrompt)(`Are you sure you want to ${type} the record ${name}?`, o);
+        // assert spawn new ant with module id
+        let antSpawnConfirmation = '';
+        if (processId === undefined) {
+            const { moduleId, version } = await ant_js_1.ANT.versions.getLatestANTVersion();
+            antSpawnConfirmation = `Note: A new ANT process will be spawned with module ${moduleId} (v${version}) and assigned to this name.`;
+        }
+        await (0, utils_js_1.assertConfirmationPrompt)(`Are you sure you want to ${type} the record ${name}? ${antSpawnConfirmation}`, o);
     }
     return ario.buyRecord({
         name: (0, utils_js_1.requiredStringFromOptions)(o, 'name'),

package/lib/cjs/common/ant.js

@@ -25,7 +25,18 @@ const schema_js_1 = require("../utils/schema.js");
 const ant_versions_js_1 = require("./ant-versions.js");
 const index_js_2 = require("./index.js");
 class ANT {
-    static versions = ant_versions_js_1.ANTVersions.init();
+    /**
+     * Versions of ANTs according to the ANT registry.
+     *
+     * Needs to be wrapped in a getter to avoid circular dependency issues.
+     */
+    static get versions() {
+        return ant_versions_js_1.ANTVersions.init();
+    }
+    /**
+     * Spawn a new ANT.
+     */
+    static spawn = ao_js_1.spawnANT;
     // implementation
     static init(config) {
         if (config !== undefined && 'signer' in config) {

package/lib/cjs/common/io.js

@@ -26,6 +26,7 @@ const arweave_js_2 = require("./arweave.js");
 const ao_process_js_1 = require("./contracts/ao-process.js");
 const error_js_1 = require("./error.js");
 const faucet_js_1 = require("./faucet.js");
+const logger_js_1 = require("./logger.js");
 const turbo_js_1 = require("./turbo.js");
 class ARIO {
     // Implementation
@@ -100,6 +101,7 @@ class ARIOReadable {
     epochSettings;
     arweave;
     paymentProvider; // TODO: this could be an array/map of payment providers
+    logger = logger_js_1.Logger.default;
     constructor(config) {
         this.arweave = config?.arweave ?? arweave_js_2.defaultArweave;
         if (config === undefined || Object.keys(config).length === 0) {
@@ -964,6 +966,23 @@ class ARIOWriteable extends ARIOReadable {
         });
     }
     async buyRecord(params, options) {
+        // spawn a new ANT if not provided
+        if (params.processId === undefined) {
+            try {
+                params.processId = await ant_js_1.ANT.spawn({
+                    signer: this.signer,
+                    ao: this.process.ao,
+                    logger: this.logger,
+                });
+            }
+            catch (error) {
+                this.logger.error('Failed to spawn ANT for name purchase.', {
+                    error,
+                });
+                throw error;
+            }
+        }
+        // pay with turbo credits if available
         if (params.fundFrom === 'turbo') {
             if (!(this.paymentProvider instanceof turbo_js_1.TurboArNSPaymentProviderAuthenticated)) {
                 throw new Error('Turbo funding is not supported for this payment provider');

package/lib/cjs/constants.js

@@ -30,7 +30,13 @@ exports.ARIO_TESTNET_PROCESS_ID = 'agYcCFJtrMG6cqMuZfskIkFTGvUPddICmtQSBIoPdiA';
 exports.ARIO_MAINNET_PROCESS_ID = 'qNvAoz0TgcH7DMg8BCVn8jF32QH5L6T29VjHxhHqqGE';
 exports.ANT_REGISTRY_ID = 'i_le_yKKPVstLTDSmkHRqf-wYphMnwB9OhleiTgMkWc';
 exports.MARIO_PER_ARIO = 1_000_000;
+/**
+ * @deprecated - use ANT.versions.getLatestANTVersion() to get latest ANT module
+ **/
 exports.AOS_MODULE_ID = 'nEjlSFA_8narJlVHApbczDPkMc9znSqYtqtf1iOdoxM';
+/**
+ * @deprecated - use ANT.versions.getLatestANTVersion() to get latest ANT module
+ **/
 exports.ANT_LUA_ID = 'sOW9Sdm1yoPRrzerC5iu1nsupp4e6I-HnJyYVHzvzQo';
 exports.AO_AUTHORITY = 'fcoN_xJeisVsPXA-trzVAuIiqO3ydLQxM-L4XbrQKzY';
 exports.DEFAULT_SCHEDULER_ID = '_GQ33BkPtZrqxA84vM8Zk-N2aO0toNNu_C-l-rawrBA';

package/lib/cjs/utils/ao.js

@@ -27,17 +27,35 @@ exports.removeUnicodeFromError = removeUnicodeFromError;
 const arbundles_1 = require("@dha-team/arbundles");
 const aoconnect_1 = require("@permaweb/aoconnect");
 const zod_1 = require("zod");
+const ant_registry_js_1 = require("../common/ant-registry.js");
+const ant_versions_js_1 = require("../common/ant-versions.js");
 const arweave_js_1 = require("../common/arweave.js");
 const index_js_1 = require("../common/index.js");
 const constants_js_1 = require("../constants.js");
 const ant_js_1 = require("../types/ant.js");
 const schema_js_1 = require("./schema.js");
-async function spawnANT({ signer, module = constants_js_1.AOS_MODULE_ID, ao = (0, aoconnect_1.connect)({
+async function spawnANT({ signer, module, ao = (0, aoconnect_1.connect)({
     MODE: 'legacy',
 }), scheduler = constants_js_1.DEFAULT_SCHEDULER_ID, state, antRegistryId = constants_js_1.ANT_REGISTRY_ID, logger = index_js_1.Logger.default, authority = constants_js_1.AO_AUTHORITY, }) {
     if (state) {
         (0, schema_js_1.parseSchemaResult)(ant_js_1.SpawnANTStateSchema, state);
     }
+    if (module === undefined) {
+        const antRegistry = ant_versions_js_1.ANTVersions.init({
+            process: new index_js_1.AOProcess({
+                processId: antRegistryId,
+                ao,
+                logger,
+            }),
+        });
+        const { moduleId: latestAntModule, version } = await antRegistry.getLatestANTVersion();
+        logger.debug('Spawning new ANT with latest module from ANT registry', {
+            moduleId: latestAntModule,
+            version,
+            antRegistryId,
+        });
+        module = latestAntModule;
+    }
     const processId = await ao.spawn({
         module,
         scheduler,
@@ -55,64 +73,139 @@ async function spawnANT({ signer, module = constants_js_1.AOS_MODULE_ID, ao = (0
             },
         ],
     });
-    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 {
+                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');
+    // 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 index_js_1.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 index_js_1.AOProcess({
-        processId,
-        ao,
-        logger,
-    });
-    await processApi.send({
-        tags: [{ name: 'Action', value: 'State' }],
+    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`);
+    }
+    // check the ACL for the owner
+    const antRegistry = ant_registry_js_1.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
+ */
 async function evolveANT({ signer, processId, luaCodeTxId = constants_js_1.ANT_LUA_ID, ao = (0, aoconnect_1.connect)({
     MODE: 'legacy',
 }), logger = index_js_1.Logger.default, arweave = arweave_js_1.defaultArweave, }) {
@@ -121,6 +214,7 @@ async function evolveANT({ signer, processId, luaCodeTxId = constants_js_1.ANT_L
         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/cjs/version.js

@@ -17,4 +17,4 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.version = void 0;
 // AUTOMATICALLY GENERATED FILE - DO NOT TOUCH
-exports.version = '3.15.1';
+exports.version = '3.16.0-alpha.1';

package/lib/esm/cli/cli.js

@@ -401,6 +401,7 @@ makeCommand({
     options: buyRecordOptions,
     action: buyRecordCLICommand,
 });
+// TODO alias buy-record with buy-name
 makeCommand({
     name: 'upgrade-record',
     description: 'Upgrade the lease of a record to a permabuy',

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

@@ -1,3 +1,19 @@
+/**
+ * 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 { ANT } from '../../common/ant.js';
 import { assertConfirmationPrompt, assertEnoughBalanceForArNSPurchase, customTagsFromOptions, fundFromFromOptions, positiveIntegerFromOptions, recordTypeFromOptions, referrerFromOptions, requiredPositiveIntegerFromOptions, requiredStringFromOptions, stringArrayFromOptions, writeARIOFromOptions, } from '../utils.js';
 export async function buyRecordCLICommand(o) {
     const { ario, signerAddress } = writeARIOFromOptions(o);
@@ -7,10 +23,6 @@ export async function buyRecordCLICommand(o) {
     const fundFrom = fundFromFromOptions(o);
     const referrer = referrerFromOptions(o);
     const processId = o.processId;
-    if (processId === undefined) {
-        // TODO: Spawn ANT process, register it to ANT registry, get process ID
-        throw new Error('Process ID must be provided for buy-record');
-    }
     if (!o.skipConfirmation) {
         const existingRecord = await ario.getArNSRecord({
             name,
@@ -30,7 +42,13 @@ export async function buyRecordCLICommand(o) {
                 fromAddress: signerAddress,
             },
         });
-        await assertConfirmationPrompt(`Are you sure you want to ${type} the record ${name}?`, o);
+        // assert spawn new ant with module id
+        let antSpawnConfirmation = '';
+        if (processId === undefined) {
+            const { moduleId, version } = await ANT.versions.getLatestANTVersion();
+            antSpawnConfirmation = `Note: A new ANT process will be spawned with module ${moduleId} (v${version}) and assigned to this name.`;
+        }
+        await assertConfirmationPrompt(`Are you sure you want to ${type} the record ${name}? ${antSpawnConfirmation}`, o);
     }
     return ario.buyRecord({
         name: requiredStringFromOptions(o, 'name'),

package/lib/esm/common/ant.js

@@ -17,12 +17,23 @@ import { z } from 'zod';
 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 } from '../utils/ao.js';
+import { createAoSigner, spawnANT } from '../utils/ao.js';
 import { parseSchemaResult } from '../utils/schema.js';
 import { ANTVersions } from './ant-versions.js';
 import { AOProcess, InvalidContractConfigurationError, Logger, } from './index.js';
 export class ANT {
-    static versions = ANTVersions.init();
+    /**
+     * Versions of ANTs according to the ANT registry.
+     *
+     * Needs to be wrapped in a getter to avoid circular dependency issues.
+     */
+    static get versions() {
+        return ANTVersions.init();
+    }
+    /**
+     * Spawn a new ANT.
+     */
+    static spawn = spawnANT;
     // implementation
     static init(config) {
         if (config !== undefined && 'signer' in config) {

package/lib/esm/common/io.js

@@ -23,6 +23,7 @@ import { defaultArweave } from './arweave.js';
 import { AOProcess } from './contracts/ao-process.js';
 import { InvalidContractConfigurationError } from './error.js';
 import { createFaucet } from './faucet.js';
+import { Logger } from './logger.js';
 import { TurboArNSPaymentFactory, TurboArNSPaymentProviderAuthenticated, isTurboArNSSigner, } from './turbo.js';
 export class ARIO {
     // Implementation
@@ -96,6 +97,7 @@ export class ARIOReadable {
     epochSettings;
     arweave;
     paymentProvider; // TODO: this could be an array/map of payment providers
+    logger = Logger.default;
     constructor(config) {
         this.arweave = config?.arweave ?? defaultArweave;
         if (config === undefined || Object.keys(config).length === 0) {
@@ -959,6 +961,23 @@ export class ARIOWriteable extends ARIOReadable {
         });
     }
     async buyRecord(params, options) {
+        // spawn a new ANT if not provided
+        if (params.processId === undefined) {
+            try {
+                params.processId = await ANT.spawn({
+                    signer: this.signer,
+                    ao: this.process.ao,
+                    logger: this.logger,
+                });
+            }
+            catch (error) {
+                this.logger.error('Failed to spawn ANT for name purchase.', {
+                    error,
+                });
+                throw error;
+            }
+        }
+        // pay with turbo credits if available
         if (params.fundFrom === 'turbo') {
             if (!(this.paymentProvider instanceof TurboArNSPaymentProviderAuthenticated)) {
                 throw new Error('Turbo funding is not supported for this payment provider');

package/lib/esm/constants.js

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