@ar.io/sdk 3.22.0-alpha.1 → 3.22.0-alpha.3

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' },
@@ -645,6 +677,7 @@ export class ARIOReadable {
                 ao: this.process.ao,
                 processId: nameData.processId,
             }),
+            hyperbeamUrl: this.hyperbeamUrl,
         });
         const [owner, antRecord] = await Promise.all([
             ant.getOwner(),
@@ -1281,6 +1314,7 @@ export class ARIOWriteable extends ARIOReadable {
                 ao: this.process.ao,
             }),
             signer: this.signer,
+            hyperbeamUrl: this.hyperbeamUrl,
         });
         // approve the primary name request with the ant
         const approveResult = await antClient.approvePrimaryNameRequest({

package/lib/esm/utils/ao.js

@@ -27,7 +27,7 @@ export async function spawnANT({ signer, module, ao = connect({
     MODE: 'legacy',
 }), scheduler = DEFAULT_SCHEDULER_ID, state, tags = [], antRegistryId = ANT_REGISTRY_ID, logger = Logger.default, authority = AO_AUTHORITY, onSigningProgress = (name, payload) => {
     logger.debug('Signing progress', { name, payload });
-}, }) {
+}, hyperbeamUrl, }) {
     if (state) {
         parseSchemaResult(SpawnANTStateSchema, state);
     }
@@ -182,7 +182,12 @@ export async function spawnANT({ signer, module, ao = connect({
     // check the ACL for the owner
     const antRegistry = ANTRegistry.init({
         signer,
-        processId: antRegistryId,
+        process: new AOProcess({
+            processId: antRegistryId,
+            ao,
+            logger,
+        }),
+        hyperbeamUrl,
     });
     let attempts = 0;
     const maxAttempts = 5;
@@ -213,7 +218,7 @@ export async function spawnANT({ signer, module, ao = connect({
 }
 export async function forkANT({ signer, antProcessId, logger = Logger.default, ao, moduleId, antRegistryId = ANT_REGISTRY_ID, onSigningProgress = (name, payload) => {
     logger.debug('Forking ANT', { name, payload });
-}, }) {
+}, hyperbeamUrl, }) {
     // get the state of the current ANT and use it to spawn a new ANT
     const ant = ANT.init({
         process: new AOProcess({
@@ -221,6 +226,7 @@ export async function forkANT({ signer, antProcessId, logger = Logger.default, a
             ao,
             logger,
         }),
+        hyperbeamUrl,
     });
     const state = await ant.getState();
     if (state === undefined) {
@@ -244,6 +250,7 @@ export async function forkANT({ signer, antProcessId, logger = Logger.default, a
             balances: state.Balances,
             logo: state.Logo,
         },
+        hyperbeamUrl,
     });
     return forkedProcessId;
 }

package/lib/esm/version.js

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

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;

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/utils/ao.d.ts

@@ -28,9 +28,10 @@ export type SpawnANTParams = {
      * Callback function to be called when signing progress is made
      */
     onSigningProgress?: (name: keyof SpawnAntProgressEvent, payload: SpawnAntProgressEvent[keyof SpawnAntProgressEvent]) => void;
+    hyperbeamUrl?: string;
 };
-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, moduleId, antRegistryId, onSigningProgress, }: {
+export declare function spawnANT({ signer, module, ao, scheduler, state, tags, antRegistryId, logger, authority, onSigningProgress, hyperbeamUrl, }: SpawnANTParams): Promise<ProcessId>;
+export declare function forkANT({ signer, antProcessId, logger, ao, moduleId, antRegistryId, onSigningProgress, hyperbeamUrl, }: {
     signer: AoSigner;
     antProcessId: string;
     moduleId?: string;
@@ -38,6 +39,7 @@ export declare function forkANT({ signer, antProcessId, logger, ao, moduleId, an
     ao?: AoClient;
     antRegistryId?: string;
     onSigningProgress?: (name: keyof SpawnAntProgressEvent, payload: SpawnAntProgressEvent[keyof SpawnAntProgressEvent]) => void;
+    hyperbeamUrl?: string;
 }): Promise<string>;
 /**
  * @deprecated

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

package/package.json

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