@ar.io/sdk 3.0.1-alpha.1 → 3.1.0-alpha.10

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

@@ -1,7 +1,7 @@
 import { JWKInterface } from 'arweave/node/lib/wallet.js';
 import { Command, OptionValues } from 'commander';
-import { ARIOToken, AoANTRead, AoANTWrite, AoARIORead, AoARIOWrite, AoRedelegateStakeParams, AoSigner, AoUpdateGatewaySettingsParams, ContractSigner, EpochInput, Logger, PaginationParams, SpawnANTState, WriteOptions, mARIOToken } from '../node/index.js';
-import { ANTStateCLIOptions, AddressCLIOptions, EpochCLIOptions, GlobalCLIOptions, InitiatorCLIOptions, JsonSerializable, PaginationCLIOptions, ProcessIdCLIOptions, RedelegateStakeCLIOptions, TransferCLIOptions, UpdateGatewaySettingsCLIOptions, WalletCLIOptions, WriteActionCLIOptions } from './types.js';
+import { ARIOToken, AoANTRead, AoANTWrite, AoARIORead, AoARIOWrite, AoGetCostDetailsParams, AoRedelegateStakeParams, AoSigner, AoUpdateGatewaySettingsParams, ContractSigner, EpochInput, FundFrom, Logger, PaginationParams, SpawnANTState, WriteOptions, mARIOToken } from '../node/index.js';
+import { ANTStateCLIOptions, AddressCLIOptions, EpochCLIOptions, GetTokenCostCLIOptions, GlobalCLIOptions, InitiatorCLIOptions, JsonSerializable, PaginationCLIOptions, ProcessIdCLIOptions, RedelegateStakeCLIOptions, TransferCLIOptions, UpdateGatewaySettingsCLIOptions, WalletCLIOptions, WriteActionCLIOptions } from './types.js';
 export declare function stringifyJsonForCLIDisplay(json: JsonSerializable | unknown): string;
 export declare function runCommand<O extends OptionValues>(command: Command, action: (options: O) => Promise<JsonSerializable>): Promise<void>;
 export interface CommanderOption {
@@ -31,6 +31,7 @@ export declare function writeARIOFromOptions(options: GlobalCLIOptions): {
     signerAddress: string;
 };
 export declare function formatARIOWithCommas(value: ARIOToken): string;
+export declare function formatMARIOToARIOWithCommas(value: mARIOToken): string;
 /** helper to get address from --address option first, then check wallet options  */
 export declare function addressFromOptions<O extends AddressCLIOptions>(options: O): string | undefined;
 export declare function requiredAddressFromOptions<O extends AddressCLIOptions>(options: O): string;
@@ -51,8 +52,17 @@ export declare function redelegateParamsFromOptions(options: RedelegateStakeCLIO
 export declare function recordTypeFromOptions<O extends {
     type?: string;
 }>(options: O): 'lease' | 'permabuy';
-export declare function requiredMIOFromOptions<O extends GlobalCLIOptions>(options: O, key: string): mARIOToken;
-export declare function assertEnoughBalance(ario: AoARIORead, address: string, arioQuantity: ARIOToken): Promise<void>;
+export declare function requiredMARIOFromOptions<O extends GlobalCLIOptions>(options: O, key: string): mARIOToken;
+export declare function assertEnoughBalanceForArNSPurchase({ ario, address, costDetailsParams, }: {
+    ario: AoARIORead;
+    address: string;
+    costDetailsParams: AoGetCostDetailsParams;
+}): Promise<void>;
+export declare function assertEnoughMARIOBalance({ address, ario, mARIOQuantity, }: {
+    ario: AoARIORead;
+    address: string;
+    mARIOQuantity: mARIOToken | number;
+}): Promise<void>;
 export declare function confirmationPrompt(message: string): Promise<boolean>;
 export declare function assertConfirmationPrompt<O extends {
     skipConfirmation?: boolean;
@@ -65,3 +75,14 @@ export declare function requiredStringArrayFromOptions<O extends GlobalCLIOption
 export declare function positiveIntegerFromOptions<O extends GlobalCLIOptions>(options: O, key: string): number | undefined;
 export declare function requiredPositiveIntegerFromOptions<O extends GlobalCLIOptions>(options: O, key: string): number;
 export declare function getANTStateFromOptions(options: ANTStateCLIOptions): SpawnANTState;
+export declare function getTokenCostParamsFromOptions(o: GetTokenCostCLIOptions): {
+    type: "lease" | "permabuy";
+    quantity: number | undefined;
+    years: number;
+    intent: "Buy-Record" | "Extend-Lease" | "Increase-Undername-Limit" | "Upgrade-Name" | "Primary-Name-Request";
+    name: string;
+    fromAddress: string | undefined;
+};
+export declare function fundFromFromOptions<O extends {
+    fundFrom?: string;
+}>(o: O): FundFrom;

package/lib/types/common/contracts/ao-process.d.ts

@@ -9,12 +9,14 @@ export declare class AOProcess implements AOContract {
         ao?: AoClient;
         logger?: ILogger;
     });
-    read<K>({ tags, retries, }: {
+    private isMessageDataEmpty;
+    read<K>({ tags, retries, fromAddress, }: {
         tags?: Array<{
             name: string;
             value: string;
         }>;
         retries?: number;
+        fromAddress?: string;
     }): Promise<K>;
     send<K>({ tags, data, signer, retries, }: {
         tags: Array<{

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

@@ -1,21 +1,5 @@
-/**
- * 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 Arweave from 'arweave';
 import { AoArNSNameDataWithName, AoArNSReservedNameData, AoBalanceWithAddress, AoEpochDistributionData, AoEpochObservationData, AoGatewayWithAddress, AoJoinNetworkParams, AoMessageResult, AoPrimaryName, AoPrimaryNameRequest, AoRedelegationFeeInfo, AoReturnedName, AoTokenSupplyData, AoUpdateGatewaySettingsParams, AoWeightedObserver, ContractSigner, PaginationParams, PaginationResult, ProcessConfiguration, TransactionId, WalletAddress, WithSigner, WriteOptions } from '../types/index.js';
-import { AoARIORead, AoARIOWrite, AoArNSNameData, AoArNSReservedNameDataWithName, AoDelegation, AoEpochData, AoEpochSettings, AoGateway, AoGatewayDelegateWithAddress, AoGatewayRegistrySettings, AoGatewayVault, AoPaginatedAddressParams, AoRegistrationFees, AoVaultData, AoWalletVault, DemandFactorSettings, EpochInput } from '../types/io.js';
+import { AoARIORead, AoARIOWrite, AoArNSNameData, AoArNSPurchaseParams, AoArNSReservedNameDataWithName, AoBuyRecordParams, AoDelegation, AoEpochData, AoEpochSettings, AoExtendLeaseParams, AoGateway, AoGatewayDelegateWithAddress, AoGatewayRegistrySettings, AoGatewayVault, AoGetCostDetailsParams, AoIncreaseUndernameLimitParams, AoPaginatedAddressParams, AoRegistrationFees, AoVaultData, AoWalletVault, CostDetailsResult, DemandFactorSettings, EpochInput } from '../types/io.js';
 import { mARIOToken } from '../types/token.js';
 import { AOProcess } from './contracts/ao-process.js';
 export declare class ARIO {
@@ -27,7 +11,7 @@ export declare class ARIO {
         process: AOProcess;
     }>): AoARIOWrite;
     static init({ processId, signer, }: WithSigner<{
-        processId: string;
+        processId?: string;
     }>): AoARIOWrite;
     static init({ processId, signer, }: {
         signer?: ContractSigner | undefined;
@@ -39,8 +23,8 @@ export declare class ARIO {
 }
 export declare class ARIOReadable implements AoARIORead {
     protected process: AOProcess;
-    private arweave;
-    constructor(config?: ProcessConfiguration, arweave?: Arweave);
+    protected epochSettings: AoEpochSettings | undefined;
+    constructor(config?: ProcessConfiguration);
     getInfo(): Promise<{
         Name: string;
         Ticker: string;
@@ -50,7 +34,9 @@ export declare class ARIOReadable implements AoARIORead {
         LastTickedEpochIndex: number;
     }>;
     getTokenSupply(): Promise<AoTokenSupplyData>;
-    getEpochSettings(params?: EpochInput): Promise<AoEpochSettings>;
+    private computeEpochIndexForTimestamp;
+    private computeEpochIndex;
+    getEpochSettings(): Promise<AoEpochSettings>;
     getEpoch(epoch?: EpochInput): Promise<AoEpochData>;
     getArNSRecord({ name, }: {
         name: string;
@@ -67,7 +53,7 @@ export declare class ARIOReadable implements AoARIORead {
     getVault({ address, vaultId, }: {
         address: WalletAddress;
         vaultId: string;
-    }): Promise<AoVaultData>;
+    }): Promise<AoVaultData | undefined>;
     getVaults(params?: PaginationParams<AoWalletVault>): Promise<PaginationResult<AoWalletVault>>;
     getGateway({ address, }: {
         address: WalletAddress;
@@ -107,6 +93,7 @@ export declare class ARIOReadable implements AoARIORead {
         intent: 'Primary-Name-Request';
         name: string;
     }): Promise<number>;
+    getCostDetails({ intent, type, years, name, quantity, fromAddress, fundFrom, }: AoGetCostDetailsParams): Promise<CostDetailsResult>;
     getRegistrationFees(): Promise<AoRegistrationFees>;
     getDemandFactor(): Promise<number>;
     getDemandFactorSettings(): Promise<DemandFactorSettings>;
@@ -124,7 +111,7 @@ export declare class ARIOReadable implements AoARIORead {
     getPrimaryNameRequest(params: {
         initiator: WalletAddress;
     }): Promise<AoPrimaryNameRequest>;
-    getPrimaryNameRequests(params: PaginationParams<AoPrimaryNameRequest>): Promise<PaginationResult<AoPrimaryNameRequest>>;
+    getPrimaryNameRequests(params?: PaginationParams<AoPrimaryNameRequest>): Promise<PaginationResult<AoPrimaryNameRequest>>;
     getPrimaryName(params: {
         address: WalletAddress;
     } | {
@@ -190,12 +177,7 @@ export declare class ARIOWriteable extends ARIOReadable implements AoARIOWrite {
         reportTxId: TransactionId;
         failedGateways: WalletAddress[];
     }, options?: WriteOptions): Promise<AoMessageResult>;
-    buyRecord(params: {
-        name: string;
-        years?: number;
-        type: 'lease' | 'permabuy';
-        processId: string;
-    }, options?: WriteOptions): Promise<AoMessageResult>;
+    buyRecord(params: AoBuyRecordParams, options?: WriteOptions): Promise<AoMessageResult>;
     /**
      * Upgrades an existing leased record to a permabuy.
      *
@@ -204,9 +186,7 @@ export declare class ARIOWriteable extends ARIOReadable implements AoARIOWrite {
      * @param {Object} [options] - The options for the upgrade
      * @returns {Promise<AoMessageResult>} The result of the upgrade
      */
-    upgradeRecord(params: {
-        name: string;
-    }, options?: WriteOptions): Promise<AoMessageResult>;
+    upgradeRecord(params: AoArNSPurchaseParams, options?: WriteOptions): Promise<AoMessageResult>;
     /**
      * Extends the lease of an existing leased record.
      *
@@ -216,14 +196,8 @@ export declare class ARIOWriteable extends ARIOReadable implements AoARIOWrite {
      * @param {Object} [options] - The options for the extension
      * @returns {Promise<AoMessageResult>} The result of the extension
      */
-    extendLease(params: {
-        name: string;
-        years: number;
-    }, options?: WriteOptions): Promise<AoMessageResult>;
-    increaseUndernameLimit(params: {
-        name: string;
-        increaseCount: number;
-    }, options?: WriteOptions): Promise<AoMessageResult>;
+    extendLease(params: AoExtendLeaseParams, options?: WriteOptions): Promise<AoMessageResult>;
+    increaseUndernameLimit(params: AoIncreaseUndernameLimitParams, options?: WriteOptions): Promise<AoMessageResult>;
     /**
      * Cancel a withdrawal from a gateway.
      *
@@ -237,9 +211,7 @@ export declare class ARIOWriteable extends ARIOReadable implements AoARIOWrite {
         gatewayAddress?: WalletAddress;
         vaultId: string;
     }, options?: WriteOptions | undefined): Promise<AoMessageResult>;
-    requestPrimaryName(params: {
-        name: string;
-    }): Promise<AoMessageResult>;
+    requestPrimaryName(params: AoArNSPurchaseParams, options?: WriteOptions): Promise<AoMessageResult>;
     /**
      * Redelegate stake from one gateway to another gateway.
      *

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

@@ -52,6 +52,7 @@ export type AoPrimaryNameRequest = {
 };
 export type AoPrimaryName = {
     owner: WalletAddress;
+    processId: ProcessId;
     name: string;
     startTimestamp: Timestamp;
 };

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

@@ -25,6 +25,7 @@ export type PaginationParams<T = Record<string, never>> = {
 export type PaginationResult<T> = {
     items: T[];
     nextCursor?: string;
+    limit: number;
     totalItems: number;
     sortBy?: T extends string ? string : keyof T;
     sortOrder: 'asc' | 'desc';
@@ -50,6 +51,7 @@ export type AoEpochObservationData = {
     failureSummaries: Record<WalletAddress, WalletAddress[]>;
     reports: Record<WalletAddress, TransactionId>;
 };
+export type AoEpochPrescribedObservers = Record<WalletAddress, WalletAddress[]>;
 export type AoVaultData = {
     balance: number;
     startTimestamp: Timestamp;
@@ -103,12 +105,15 @@ export type AoEpochSettings = {
     rewardPercentage: number;
     maxObservers: number;
     distributionDelayMs: number;
+    epochZeroTimestamp: Timestamp;
+    pruneEpochsCount: number;
 };
 export type AoEpochData = {
     epochIndex: AoEpochIndex;
     startHeight: BlockHeight;
     observations: AoEpochObservationData;
     prescribedObservers: AoWeightedObserver[];
+    prescribedNames: string[];
     startTimestamp: Timestamp;
     endTimestamp: Timestamp;
     distributionTimestamp: Timestamp;
@@ -252,30 +257,60 @@ export type AoRedelegateStakeParams = {
     stakeQty: number | mARIOToken;
     vaultId?: string;
 };
-export declare const validIntents: string[];
-export declare const intentsUsingYears: string[];
+export declare const validIntents: readonly ["Buy-Record", "Extend-Lease", "Increase-Undername-Limit", "Upgrade-Name", "Primary-Name-Request"];
+export declare const intentsUsingYears: readonly ["Buy-Record", "Extend-Lease"];
 export type Intent = (typeof validIntents)[number];
-export declare const isValidIntent: (intent: string) => intent is string;
+export declare const isValidIntent: (intent: string) => intent is "Buy-Record" | "Extend-Lease" | "Increase-Undername-Limit" | "Upgrade-Name" | "Primary-Name-Request";
 export type AoTokenCostParams = {
     intent: Intent;
     type?: 'permabuy' | 'lease';
     years?: number;
     name: string;
     quantity?: number;
+    fromAddress?: WalletAddress;
+};
+export declare const fundFromOptions: readonly ["balance", "stakes", "any"];
+export type FundFrom = (typeof fundFromOptions)[number];
+export declare const isValidFundFrom: (fundFrom: string) => fundFrom is "balance" | "stakes" | "any";
+export type AoGetCostDetailsParams = AoTokenCostParams & {
+    fundFrom?: FundFrom;
+};
+export type AoFundingPlan = {
+    address: WalletAddress;
+    balance: number;
+    stakes: Record<WalletAddress, {
+        vaults: string[];
+        delegatedStake: number;
+    }>;
+    /** Any remaining shortfall will indicate an insufficient balance for the action */
+    shortfall: number;
+};
+export type CostDiscount = {
+    name: string;
+    discountTotal: number;
+    multiplier: number;
+};
+export type CostDetailsResult = {
+    tokenCost: number;
+    discounts: CostDiscount[];
+    fundingPlan?: AoFundingPlan;
 };
 export type AoGetVaultParams = {
     address: WalletAddress;
     vaultId: string;
 };
-export type AoBuyRecordParams = AoArNSNameParams & {
+export type AoArNSPurchaseParams = AoArNSNameParams & {
+    fundFrom?: FundFrom;
+};
+export type AoBuyRecordParams = AoArNSPurchaseParams & {
     years?: number;
     type: 'lease' | 'permabuy';
     processId: string;
 };
-export type AoExtendLeaseParams = AoArNSNameParams & {
+export type AoExtendLeaseParams = AoArNSPurchaseParams & {
     years: number;
 };
-export type AoIncreaseUndernameLimitParams = AoArNSNameParams & {
+export type AoIncreaseUndernameLimitParams = AoArNSPurchaseParams & {
     increaseCount: number;
 };
 export type AoGatewayRegistrySettings = {
@@ -318,7 +353,7 @@ export interface AoARIORead {
         LastTickedEpochIndex: number;
     }>;
     getTokenSupply(): Promise<AoTokenSupplyData>;
-    getEpochSettings(params?: EpochInput): Promise<AoEpochSettings>;
+    getEpochSettings(): Promise<AoEpochSettings>;
     getGateway({ address }: AoAddressParams): Promise<AoGateway | undefined>;
     getGatewayDelegates({ address, ...pageParams }: AoAddressParams & PaginationParams<AoGatewayDelegateWithAddress>): Promise<PaginationResult<AoGatewayDelegateWithAddress>>;
     getGatewayDelegateAllowList(params: AoPaginatedAddressParams): Promise<PaginationResult<WalletAddress>>;
@@ -353,6 +388,7 @@ export interface AoARIORead {
     getObservations(epoch?: EpochInput): Promise<AoEpochObservationData>;
     getDistributions(epoch?: EpochInput): Promise<AoEpochDistributionData>;
     getTokenCost({ intent, type, years, name, quantity, }: AoTokenCostParams): Promise<number>;
+    getCostDetails({ intent, type, years, name, quantity, fundFrom, }: AoGetCostDetailsParams): Promise<CostDetailsResult>;
     getRegistrationFees(): Promise<AoRegistrationFees>;
     getDemandFactor(): Promise<number>;
     getDemandFactorSettings(): Promise<DemandFactorSettings>;
@@ -361,7 +397,7 @@ export interface AoARIORead {
     getPrimaryNameRequest(params: {
         initiator: WalletAddress;
     }): Promise<AoPrimaryNameRequest>;
-    getPrimaryNameRequests(params: PaginationParams<AoPrimaryNameRequest>): Promise<PaginationResult<AoPrimaryNameRequest>>;
+    getPrimaryNameRequests(params?: PaginationParams<AoPrimaryNameRequest>): Promise<PaginationResult<AoPrimaryNameRequest>>;
     getPrimaryName(params: {
         address: WalletAddress;
     } | {
@@ -406,16 +442,14 @@ export interface AoARIOWrite extends AoARIORead {
         failedGateways: WalletAddress[];
     }, options?: WriteOptions): Promise<AoMessageResult>;
     buyRecord(params: AoBuyRecordParams, options?: WriteOptions): Promise<AoMessageResult>;
-    upgradeRecord(params: AoArNSNameParams, options?: WriteOptions): Promise<AoMessageResult>;
+    upgradeRecord(params: AoArNSPurchaseParams, options?: WriteOptions): Promise<AoMessageResult>;
     extendLease(params: AoExtendLeaseParams, options?: WriteOptions): Promise<AoMessageResult>;
     increaseUndernameLimit(params: AoIncreaseUndernameLimitParams, options?: WriteOptions): Promise<AoMessageResult>;
     cancelWithdrawal(params: {
         gatewayAddress?: WalletAddress;
         vaultId: string;
     }, options?: WriteOptions): Promise<AoMessageResult>;
-    requestPrimaryName(params: {
-        name: string;
-    }): Promise<AoMessageResult>;
+    requestPrimaryName(params: AoArNSPurchaseParams, options?: WriteOptions): Promise<AoMessageResult>;
     redelegateStake(params: AoRedelegateStakeParams, options?: WriteOptions): Promise<AoMessageResult>;
 }
 export declare function isProcessConfiguration(config: object): config is {

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

@@ -1,23 +1,12 @@
-/**
- * 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 Arweave from 'arweave';
-import { BlockHeight, Timestamp } from '../types/common.js';
+import { BlockHeight } from '../types/common.js';
 import { PaginationParams } from '../types/io.js';
 export declare const validateArweaveId: (id: string) => boolean;
 export declare function isBlockHeight(height: string | number): height is BlockHeight;
+/**
+ * Prune tags that are undefined or empty.
+ * @param tags - The tags to prune.
+ * @returns The pruned tags.
+ */
 export declare const pruneTags: (tags: {
     name: string;
     value: string | undefined;
@@ -25,7 +14,6 @@ export declare const pruneTags: (tags: {
     name: string;
     value: string;
 }[];
-export declare const getCurrentBlockUnixTimestampMs: (arweave: Arweave) => Promise<Timestamp>;
 export declare const paginationParamsToTags: <T>(params?: PaginationParams<T>) => {
     name: string;
     value: 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.0.0";
+export declare const version = "3.1.0-alpha.9";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ar.io/sdk",
-  "version": "3.0.1-alpha.1",
+  "version": "3.1.0-alpha.10",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/ar-io/ar-io-sdk.git"
@@ -127,7 +127,7 @@
     "@dha-team/arbundles": "^1.0.1",
     "@permaweb/aoconnect": "^0.0.57",
     "arweave": "1.14.4",
-    "axios": "1.7.8",
+    "axios": "1.7.9",
     "axios-retry": "^4.3.0",
     "commander": "^12.1.0",
     "eventemitter3": "^5.0.1",