@ar.io/sdk 3.21.1-alpha.1 → 3.22.0-alpha.2

package/lib/esm/common/io.js

@@ -24,6 +24,7 @@ import { defaultArweave } from './arweave.js';
 import { AOProcess } from './contracts/ao-process.js';
 import { InvalidContractConfigurationError } from './error.js';
 import { createFaucet } from './faucet.js';
+import { HB } from './hyperbeam/hb.js';
 import { Logger } from './logger.js';
 import { TurboArNSPaymentFactory, TurboArNSPaymentProviderAuthenticated, isTurboArNSSigner, } from './turbo.js';
 export class ARIO {
@@ -100,9 +101,9 @@ export class ARIOReadable {
     hyperbeamUrl;
     paymentProvider; // TODO: this could be an array/map of payment providers
     logger = Logger.default;
+    hb;
     constructor(config) {
         this.arweave = config?.arweave ?? defaultArweave;
-        this.hyperbeamUrl = config?.hyperbeamUrl;
         if (config === undefined || Object.keys(config).length === 0) {
             this.process = new AOProcess({
                 processId: ARIO_MAINNET_PROCESS_ID,
@@ -119,6 +120,19 @@ export class ARIOReadable {
         else {
             throw new InvalidContractConfigurationError();
         }
+        // only use hyperbeam if the client has provided a hyperbeamUrl
+        // this will avoid overwhelming the HyperBeam node with requests
+        // as we shift using HyperBEAM for all ANT operations
+        if (config?.hyperbeamUrl !== undefined) {
+            this.hyperbeamUrl = config.hyperbeamUrl;
+            this.hb = new HB({
+                url: this.hyperbeamUrl,
+                processId: this.process.processId,
+            });
+            this.logger.debug(`Using HyperBEAM node for process ${this.process.processId}`, {
+                hyperbeamUrl: this.hyperbeamUrl,
+            });
+        }
         this.paymentProvider = TurboArNSPaymentFactory.init({
             paymentUrl: config?.paymentUrl,
         });
@@ -218,6 +232,24 @@ export class ARIOReadable {
         });
     }
     async getBalance({ address }) {
+        if (this.hb && (await this.hb.checkHyperBeamCompatibility())) {
+            this.logger.debug('Getting balance from HyperBEAM', { address });
+            const res = await this.hb
+                .compute({
+                path: `balances/${address}`,
+            })
+                .then((res) => Number(res))
+                .catch((error) => {
+                this.logger.error('Failed to get balance from HyperBEAM', {
+                    cause: error,
+                });
+                return null;
+            });
+            if (res !== null)
+                return res;
+            // else fall through to CU read
+            this.logger.info('Failed to get balance from HyperBEAM, failing over to to CU read', { address });
+        }
         return this.process.read({
             tags: [
                 { name: 'Action', value: 'Balance' },
@@ -816,7 +848,7 @@ export class ARIOWriteable extends ARIOReadable {
             signer: this.signer,
         });
     }
-    async joinNetwork({ operatorStake, allowDelegatedStaking, allowedDelegates, delegateRewardShareRatio, fqdn, label, minDelegatedStake, note, port, properties, protocol, autoStake, observerAddress, }, options) {
+    async joinNetwork({ operatorStake, allowDelegatedStaking, allowedDelegates, delegateRewardShareRatio, fqdn, label, minDelegatedStake, note, port, properties, protocol, autoStake, observerAddress, services, }, options) {
         const { tags = [] } = options || {};
         const allTags = [
             ...tags,
@@ -873,6 +905,10 @@ export class ARIOWriteable extends ARIOReadable {
                 name: 'Observer-Address',
                 value: observerAddress,
             },
+            {
+                name: 'Services',
+                value: services ? JSON.stringify(services) : undefined,
+            },
         ];
         return this.process.send({
             signer: this.signer,
@@ -886,7 +922,7 @@ export class ARIOWriteable extends ARIOReadable {
             tags: [...tags, { name: 'Action', value: 'Leave-Network' }],
         });
     }
-    async updateGatewaySettings({ allowDelegatedStaking, allowedDelegates, delegateRewardShareRatio, fqdn, label, minDelegatedStake, note, port, properties, protocol, autoStake, observerAddress, }, options) {
+    async updateGatewaySettings({ allowDelegatedStaking, allowedDelegates, delegateRewardShareRatio, fqdn, label, minDelegatedStake, note, port, properties, protocol, autoStake, observerAddress, services, }, options) {
         const { tags = [] } = options || {};
         const allTags = [
             ...tags,
@@ -915,6 +951,10 @@ export class ARIOWriteable extends ARIOReadable {
                 value: minDelegatedStake?.valueOf().toString(),
             },
             { name: 'Auto-Stake', value: autoStake?.toString() },
+            {
+                name: 'Services',
+                value: services ? JSON.stringify(services) : undefined,
+            },
         ];
         return this.process.send({
             signer: this.signer,

package/lib/esm/version.js

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

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

@@ -133,6 +133,10 @@ export declare const optionMap: {
         description: string;
         type: string;
     };
+    services: {
+        alias: string;
+        description: string;
+    };
     skipConfirmation: {
         alias: string;
         description: string;

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

@@ -46,7 +46,8 @@ export declare function paginationParamsFromOptions<O extends PaginationCLIOptio
 export declare function epochInputFromOptions(options: EpochCLIOptions): EpochInput;
 export declare function requiredInitiatorFromOptions(options: InitiatorCLIOptions): string;
 export declare function customTagsFromOptions<O extends WriteActionCLIOptions>(options: O): WriteOptions;
-export declare function gatewaySettingsFromOptions({ allowDelegatedStaking, autoStake, delegateRewardShareRatio, fqdn, label, minDelegatedStake, note, observerAddress, port, properties, allowedDelegates, }: UpdateGatewaySettingsCLIOptions): AoUpdateGatewaySettingsParams;
+export declare function servicesFromOptions(services?: string): any;
+export declare function gatewaySettingsFromOptions(options: UpdateGatewaySettingsCLIOptions): AoUpdateGatewaySettingsParams;
 export declare function requiredTargetAndQuantityFromOptions(options: TransferCLIOptions): {
     target: string;
     arioQuantity: ARIOToken;

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

@@ -0,0 +1,88 @@
+/**
+ * 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 { JSONValue } from '../../types/common.js';
+import { Logger } from '../logger.js';
+export type HBConfig = {
+    url: string;
+    processId: string;
+    logger?: Logger;
+    hbTimeoutMs?: number;
+};
+export declare class HB {
+    readonly url: string;
+    readonly processId: string;
+    protected isHyperBeamCompatible: boolean | undefined;
+    protected checkHyperBeamPromise: Promise<boolean> | undefined;
+    private logger;
+    private hbTimeoutMs;
+    constructor(config: HBConfig);
+    /**
+     * fetches the meta data for the process
+     *
+     * @returns The meta data for the process
+     *
+     * @example
+     * const hyperbeam = new Hyperbeam({ url: 'https://hyperbeam.ario.permaweb.services', processId: 'qNvAoz0TgcH7DMg8BCVn8jF32QH5L6T29VjHxhHqqGE' });
+     * const meta = await hyperbeam.meta();
+     * console.log(meta);
+     */
+    meta(): Promise<Record<string, JSONValue>>;
+    /**
+     * calls the process device /now function, which evaluates the current process state pulling new messages
+     * to get the latest state
+     *
+     * @param path - The path to the hb state
+     * @param json - Whether to return the result as JSON, defaults to true
+     * @returns The result of the compute operation
+     *
+     * @example
+     * const hyperbeam = new Hyperbeam({ url: 'https://hyperbeam.ario.permaweb.services', processId: 'qNvAoz0TgcH7DMg8BCVn8jF32QH5L6T29VjHxhHqqGE' });
+     * const result = await hyperbeam.now({ path: 'balances/QGWqtJdLLgm2ehFWiiPzMaoFLD50CnGuzZIPEdoDRGQ' });
+     * console.log(result);
+     */
+    now<T extends JSONValue>({ path, json, }: {
+        path: string;
+        json?: boolean;
+    }): Promise<T>;
+    /**
+     * calls the process device /compute function, which uses the currently evaluated state in the node
+     *
+     * @param path - The path to the compute resource
+     * @param json - Whether to return the result as JSON, defaults to true
+     * @returns The result of the compute operation
+     *
+     * @example
+     * const hyperbeam = new Hyperbeam({ url: 'https://hyperbeam.ario.permaweb.services', processId: 'qNvAoz0TgcH7DMg8BCVn8jF32QH5L6T29VjHxhHqqGE' });
+     * const result = await hyperbeam.compute({ path: 'balances/QGWqtJdLLgm2ehFWiiPzMaoFLD50CnGuzZIPEdoDRGQ' });
+     * console.log(result);
+     */
+    compute<T extends JSONValue>({ path, json, }: {
+        path: string;
+        json?: boolean;
+    }): Promise<T>;
+    /**
+     * Checks if the process is HyperBeam compatible and caches the result.
+     *
+     * @returns {Promise<boolean>} True if the process is HyperBeam compatible, false otherwise.
+     */
+    checkHyperBeamCompatibility({ minSlot, }?: {
+        minSlot?: number;
+    }): Promise<boolean>;
+    fetchHyperbeamPath<T extends JSONValue>({ path, json, }: {
+        path: string;
+        json?: boolean;
+    }): Promise<T>;
+}

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, AoCreatePrimaryNameRequest, 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, BuyArNSNameProgressEvents, CostDetailsResult, DemandFactorSettings, EpochInput, OptionalArweave, OptionalPaymentUrl, PaginationParams, PaginationResult, ProcessConfiguration, SetPrimaryNameProgressEvents, TransactionId, WalletAddress, WithSigner, WriteOptions, mARIOToken } from '../types/index.js';
 import { AOProcess } from './contracts/ao-process.js';
+import { HB } from './hyperbeam/hb.js';
 import { Logger } from './logger.js';
 import { TurboArNSPaymentProviderAuthenticated, TurboArNSPaymentProviderUnauthenticated } from './turbo.js';
 type ARIOConfigNoSigner = OptionalPaymentUrl<OptionalArweave<ProcessConfiguration & {
@@ -31,6 +32,7 @@ export declare class ARIOReadable implements AoARIORead, ArNSNameResolver {
     protected hyperbeamUrl: string | undefined;
     protected paymentProvider: TurboArNSPaymentProviderUnauthenticated;
     protected logger: Logger;
+    protected hb: HB | undefined;
     constructor(config?: ARIOConfigNoSigner);
     getInfo(): Promise<{
         Name: string;
@@ -172,9 +174,9 @@ export declare class ARIOWriteable extends ARIOReadable implements AoARIOWrite {
     createVault({ lockLengthMs, quantity }: AoCreateVaultParams, options?: WriteOptions): Promise<AoMessageResult>;
     extendVault({ vaultId, extendLengthMs }: AoExtendVaultParams, options?: WriteOptions): Promise<AoMessageResult>;
     increaseVault({ vaultId, quantity }: AoIncreaseVaultParams, options?: WriteOptions): Promise<AoMessageResult>;
-    joinNetwork({ operatorStake, allowDelegatedStaking, allowedDelegates, delegateRewardShareRatio, fqdn, label, minDelegatedStake, note, port, properties, protocol, autoStake, observerAddress, }: AoJoinNetworkParams, options?: WriteOptions): Promise<AoMessageResult>;
+    joinNetwork({ operatorStake, allowDelegatedStaking, allowedDelegates, delegateRewardShareRatio, fqdn, label, minDelegatedStake, note, port, properties, protocol, autoStake, observerAddress, services, }: AoJoinNetworkParams, options?: WriteOptions): Promise<AoMessageResult>;
     leaveNetwork(options?: WriteOptions): Promise<AoMessageResult>;
-    updateGatewaySettings({ allowDelegatedStaking, allowedDelegates, delegateRewardShareRatio, fqdn, label, minDelegatedStake, note, port, properties, protocol, autoStake, observerAddress, }: AoUpdateGatewaySettingsParams, options?: WriteOptions): Promise<AoMessageResult>;
+    updateGatewaySettings({ allowDelegatedStaking, allowedDelegates, delegateRewardShareRatio, fqdn, label, minDelegatedStake, note, port, properties, protocol, autoStake, observerAddress, services, }: AoUpdateGatewaySettingsParams, options?: WriteOptions): Promise<AoMessageResult>;
     delegateStake(params: {
         target: string;
         stakeQty: number | mARIOToken;

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

@@ -206,3 +206,6 @@ export type MessageResult = {
     Spawns: any[];
     Error?: any;
 };
+export type JSONValue = string | number | boolean | null | JSONValue[] | {
+    [key: string]: JSONValue;
+};

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

@@ -278,6 +278,7 @@ export type AoAllGatewayVaults = AoGatewayVault & {
 };
 export type AoJoinNetworkParams = Pick<AoGateway, 'operatorStake'> & Partial<AoGatewaySettings> & {
     observerAddress?: WalletAddress;
+    services?: AoGatewayServices;
 };
 export type AoUpdateGatewaySettingsParams = AtLeastOne<Omit<AoJoinNetworkParams, 'operatorStake'>>;
 export type AoArNSNameParams = {

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

package/package.json

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