@ar.io/sdk 2.6.0-alpha.4 → 2.7.0-alpha.1

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

@@ -0,0 +1,66 @@
+import { JWKInterface } from 'arweave/node/lib/wallet.js';
+import { Command, OptionValues } from 'commander';
+import { AoANTRead, AoANTWrite, AoIORead, AoIOWrite, AoRedelegateStakeParams, AoSigner, AoUpdateGatewaySettingsParams, ContractSigner, EpochInput, IOToken, Logger, PaginationParams, SpawnANTState, WriteOptions, mIOToken } from '../node/index.js';
+import { ANTStateCLIOptions, AddressCLIOptions, EpochCLIOptions, 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 {
+    alias: string;
+    description: string;
+    default?: string | boolean;
+}
+export declare function makeCommand<O extends OptionValues = GlobalCLIOptions>({ description, name, options, action, }: {
+    name: string;
+    description: string;
+    action?: (options: O) => Promise<JsonSerializable>;
+    options?: CommanderOption[];
+}): Command;
+export declare function ioProcessIdFromOptions({ ioProcessId, dev, }: GlobalCLIOptions): string;
+export declare function requiredJwkFromOptions(options: WalletCLIOptions): JWKInterface;
+export declare function jwkToAddress(jwk: JWKInterface): string;
+export declare function getLoggerFromOptions(options: GlobalCLIOptions): Logger;
+export declare function readIOFromOptions(options: GlobalCLIOptions): AoIORead;
+export declare function requiredContractSignerFromOptions(options: WalletCLIOptions): {
+    signer: ContractSigner;
+    signerAddress: string;
+};
+export declare function requiredAoSignerFromOptions(options: WalletCLIOptions): AoSigner;
+export declare function writeIOFromOptions(options: GlobalCLIOptions): {
+    io: AoIOWrite;
+    signerAddress: string;
+};
+export declare function formatIOWithCommas(value: IOToken): 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;
+export declare function paginationParamsFromOptions<O extends PaginationCLIOptions>(options: O): PaginationParams & {
+    sortBy: any;
+};
+export declare function epochInputFromOptions(options: EpochCLIOptions): EpochInput;
+export declare function requiredInitiatorFromOptions(options: InitiatorCLIOptions): string;
+export declare function writeActionTagsFromOptions<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 requiredTargetAndQuantityFromOptions(options: TransferCLIOptions): {
+    target: string;
+    ioQuantity: IOToken;
+};
+export declare function redelegateParamsFromOptions(options: RedelegateStakeCLIOptions): AoRedelegateStakeParams & {
+    stakeQty: mIOToken;
+};
+export declare function recordTypeFromOptions<O extends {
+    type?: string;
+}>(options: O): 'lease' | 'permabuy';
+export declare function requiredMIOFromOptions<O extends GlobalCLIOptions>(options: O, key: string): mIOToken;
+export declare function assertEnoughBalance(io: AoIORead, address: string, ioQuantity: IOToken): Promise<void>;
+export declare function confirmationPrompt(message: string): Promise<boolean>;
+export declare function assertConfirmationPrompt<O extends {
+    skipConfirmation?: boolean;
+}>(message: string, options: O): Promise<boolean>;
+export declare function requiredProcessIdFromOptions<O extends ProcessIdCLIOptions>(o: O): string;
+export declare function readANTFromOptions(options: ProcessIdCLIOptions): AoANTRead;
+export declare function writeANTFromOptions(options: ProcessIdCLIOptions, signer?: ContractSigner): AoANTWrite;
+export declare function requiredStringFromOptions<O extends GlobalCLIOptions>(options: O, key: string): string;
+export declare function requiredStringArrayFromOptions<O extends GlobalCLIOptions>(options: O, key: string): string[];
+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;

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

@@ -15,7 +15,7 @@
  */
 import Arweave from 'arweave';
 import { AoArNSNameDataWithName, AoArNSReservedNameData, AoAuction, AoBalanceWithAddress, AoEpochDistributionData, AoEpochObservationData, AoGatewayWithAddress, AoJoinNetworkParams, AoMessageResult, AoPrimaryName, AoPrimaryNameRequest, AoRedelegationFeeInfo, AoTokenSupplyData, AoUpdateGatewaySettingsParams, AoWeightedObserver, ContractSigner, PaginationParams, PaginationResult, ProcessConfiguration, TransactionId, WalletAddress, WithSigner, WriteOptions } from '../types/index.js';
-import { AoArNSNameData, AoArNSReservedNameDataWithName, AoAuctionPriceData, AoDelegation, AoEpochData, AoEpochSettings, AoGateway, AoGatewayDelegateWithAddress, AoGatewayRegistrySettings, AoGatewayVault, AoIORead, AoIOWrite, AoRegistrationFees, AoVaultData, AoWalletVault, DemandFactorSettings, EpochInput } from '../types/io.js';
+import { AoArNSNameData, AoArNSReservedNameDataWithName, AoAuctionPriceData, AoDelegation, AoEpochData, AoEpochSettings, AoGateway, AoGatewayDelegateWithAddress, AoGatewayRegistrySettings, AoGatewayVault, AoIORead, AoIOWrite, AoPaginatedAddressParams, AoRegistrationFees, AoVaultData, AoWalletVault, DemandFactorSettings, EpochInput } from '../types/io.js';
 import { mIOToken } from '../types/token.js';
 import { AOProcess } from './contracts/ao-process.js';
 export declare class IO {
@@ -76,9 +76,7 @@ export declare class IOReadable implements AoIORead {
         [x: string]: any;
         address: any;
     }): Promise<PaginationResult<AoGatewayDelegateWithAddress>>;
-    getGatewayDelegateAllowList({ address, ...pageParams }: {
-        address: WalletAddress;
-    } & PaginationParams<WalletAddress>): Promise<PaginationResult<WalletAddress>>;
+    getGatewayDelegateAllowList({ address, ...pageParams }: AoPaginatedAddressParams): Promise<PaginationResult<WalletAddress>>;
     getGateways(pageParams?: PaginationParams<AoGatewayWithAddress>): Promise<PaginationResult<AoGatewayWithAddress>>;
     getCurrentEpoch(): Promise<AoEpochData>;
     getPrescribedObservers(epoch?: EpochInput): Promise<AoWeightedObserver[]>;
@@ -137,9 +135,7 @@ export declare class IOReadable implements AoIORead {
     getDelegations(params: PaginationParams<AoDelegation> & {
         address: WalletAddress;
     }): Promise<PaginationResult<AoDelegation>>;
-    getAllowedDelegates(params: PaginationParams & {
-        address: WalletAddress;
-    }): Promise<PaginationResult<WalletAddress>>;
+    getAllowedDelegates(params: AoPaginatedAddressParams): Promise<PaginationResult<WalletAddress>>;
     getGatewayVaults(params: PaginationParams<AoGatewayVault> & {
         address: WalletAddress;
     }): Promise<PaginationResult<AoGatewayVault>>;
@@ -206,6 +202,7 @@ export declare class IOWriteable extends IOReadable implements AoIOWrite {
     }, options?: WriteOptions): Promise<AoMessageResult>;
     decreaseOperatorStake(params: {
         decreaseQty: number | mIOToken;
+        instant?: boolean;
     }, options?: WriteOptions): Promise<AoMessageResult>;
     saveObservations(params: {
         reportTxId: TransactionId;

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

@@ -24,9 +24,9 @@ export type PaginationParams<T = Record<string, never>> = {
 };
 export type PaginationResult<T> = {
     items: T[];
-    nextCursor: string | undefined;
+    nextCursor?: string;
     totalItems: number;
-    sortBy?: keyof T;
+    sortBy?: T extends string ? string : keyof T;
     sortOrder: 'asc' | 'desc';
     hasMore: boolean;
 };
@@ -131,7 +131,7 @@ export type AoGatewayService = {
 };
 export type AoGatewayServices = {
     bundlers: AoGatewayService[];
-} | undefined;
+};
 export type AoGatewayDelegates = Record<WalletAddress, AoGatewayDelegate>;
 export type AoGatewayDelegateAllowList = WalletAddress[];
 export type AoWalletVault = AoVaultData & {
@@ -148,7 +148,7 @@ export type AoGateway = {
     operatorStake: number;
     status: 'joined' | 'leaving';
     weights: AoGatewayWeights;
-    services: AoGatewayServices;
+    services?: AoGatewayServices;
 };
 export type AoGatewayStats = {
     passedConsecutiveEpochs: number;
@@ -243,8 +243,68 @@ export type AoGatewayVault = {
     endTimestamp: Timestamp;
     startTimestamp: Timestamp;
 };
-export type AoJoinNetworkParams = Pick<AoGateway, 'operatorStake' | 'observerAddress'> & Partial<AoGatewaySettings>;
-export type AoUpdateGatewaySettingsParams = AtLeastOne<AoJoinNetworkParams>;
+export type AoJoinNetworkParams = Pick<AoGateway, 'operatorStake'> & Partial<AoGatewaySettings> & {
+    observerAddress?: WalletAddress;
+};
+export type AoUpdateGatewaySettingsParams = AtLeastOne<Omit<AoJoinNetworkParams, 'operatorStake'>>;
+export type AoArNSNameParams = {
+    name: string;
+};
+export type AoAddressParams = {
+    address: WalletAddress;
+};
+export type AoBalanceParams = AoAddressParams;
+export type AoPaginatedAddressParams = PaginationParams & AoAddressParams;
+export type AoDelegateStakeParams = {
+    target: WalletAddress;
+    stakeQty: number | mIOToken;
+};
+export type AoGetArNSRecordsParams = PaginationParams<AoArNSNameDataWithName>;
+export type AoArNSAuctionPricesParams = {
+    name: string;
+    type: 'lease' | 'permabuy';
+    years?: number;
+    timestamp?: number;
+    intervalMs?: number;
+};
+export type AoRedelegateStakeParams = {
+    target: string;
+    source: string;
+    stakeQty: number | mIOToken;
+    vaultId?: string;
+};
+export declare const validIntents: string[];
+export declare const intentsUsingYears: string[];
+export type Intent = (typeof validIntents)[number];
+export declare const isValidIntent: (intent: string) => intent is string;
+export type AoTokenCostParams = {
+    intent: Intent;
+    type?: 'permabuy' | 'lease';
+    years?: number;
+    name: string;
+    quantity?: number;
+};
+export type AoGetVaultParams = {
+    address: WalletAddress;
+    vaultId: string;
+};
+export type AoBuyRecordParams = AoArNSNameParams & {
+    years?: number;
+    type: 'lease' | 'permabuy';
+    processId: string;
+};
+export type AoExtendLeaseParams = AoArNSNameParams & {
+    years: number;
+};
+export type AoIncreaseUndernameLimitParams = AoArNSNameParams & {
+    increaseCount: number;
+};
+export type AoSubmitAuctionBidParams = AoArNSNameParams & {
+    processId: string;
+    quantity?: number;
+    type?: 'lease' | 'permabuy';
+    years?: number;
+};
 export type AoGatewayRegistrySettings = {
     delegates: {
         minStake: number;
@@ -286,20 +346,14 @@ export interface AoIORead {
     }>;
     getTokenSupply(): Promise<AoTokenSupplyData>;
     getEpochSettings(params?: EpochInput): Promise<AoEpochSettings>;
-    getGateway({ address, }: {
-        address: WalletAddress;
-    }): Promise<AoGateway | undefined>;
-    getGatewayDelegates({ address, ...pageParams }: {
-        address: WalletAddress;
-    } & PaginationParams<AoGatewayDelegateWithAddress>): Promise<PaginationResult<AoGatewayDelegateWithAddress>>;
-    getGatewayDelegateAllowList(params?: PaginationParams<WalletAddress>): Promise<PaginationResult<WalletAddress>>;
+    getGateway({ address }: AoAddressParams): Promise<AoGateway | undefined>;
+    getGatewayDelegates({ address, ...pageParams }: AoAddressParams & PaginationParams<AoGatewayDelegateWithAddress>): Promise<PaginationResult<AoGatewayDelegateWithAddress>>;
+    getGatewayDelegateAllowList(params: AoPaginatedAddressParams): Promise<PaginationResult<WalletAddress>>;
     getGateways(params?: PaginationParams<AoGatewayWithAddress>): Promise<PaginationResult<AoGatewayWithAddress>>;
     getDelegations(params: PaginationParams<AoDelegation> & {
         address: WalletAddress;
     }): Promise<PaginationResult<AoDelegation>>;
-    getAllowedDelegates(params: PaginationParams & {
-        address: WalletAddress;
-    }): Promise<PaginationResult<WalletAddress>>;
+    getAllowedDelegates(params: AoPaginatedAddressParams): Promise<PaginationResult<WalletAddress>>;
     getGatewayVaults(params: PaginationParams<AoGatewayVault> & {
         address: WalletAddress;
     }): Promise<PaginationResult<AoGatewayVault>>;
@@ -310,7 +364,7 @@ export interface AoIORead {
     getArNSRecord({ name, }: {
         name: string;
     }): Promise<AoArNSNameData | undefined>;
-    getArNSRecords(params?: PaginationParams<AoArNSNameDataWithName>): Promise<PaginationResult<AoArNSNameDataWithName>>;
+    getArNSRecords(params?: AoGetArNSRecordsParams): Promise<PaginationResult<AoArNSNameDataWithName>>;
     getArNSReservedNames(params?: PaginationParams<AoArNSReservedNameDataWithName>): Promise<PaginationResult<AoArNSReservedNameDataWithName>>;
     getArNSReservedName({ name, }: {
         name: string;
@@ -319,34 +373,19 @@ export interface AoIORead {
     getArNSAuction({ name }: {
         name: string;
     }): Promise<AoAuction | undefined>;
-    getArNSAuctionPrices({ name, type, years, timestamp, intervalMs, }: {
-        name: string;
-        type: 'lease' | 'permabuy';
-        years?: number;
-        timestamp?: number;
-        intervalMs?: number;
-    }): Promise<AoAuctionPriceData>;
-    getEpoch(epoch?: EpochInput): Promise<AoEpochData>;
+    getArNSAuctionPrices({ name, type, years, timestamp, intervalMs, }: AoArNSAuctionPricesParams): Promise<AoAuctionPriceData>;
+    getEpoch(epoch?: EpochInput): Promise<AoEpochData | undefined>;
     getCurrentEpoch(): Promise<AoEpochData>;
     getPrescribedObservers(epoch?: EpochInput): Promise<AoWeightedObserver[]>;
     getPrescribedNames(epoch?: EpochInput): Promise<string[]>;
     getObservations(epoch?: EpochInput): Promise<AoEpochObservationData>;
     getDistributions(epoch?: EpochInput): Promise<AoEpochDistributionData>;
-    getTokenCost({ intent, type, years, name, quantity, }: {
-        intent: 'Buy-Record' | 'Extend-Lease' | 'Increase-Undername-Limit' | 'Upgrade-Name' | 'Primary-Name-Request';
-        type?: 'permabuy' | 'lease';
-        years?: number;
-        name: string;
-        quantity?: number;
-    }): Promise<number>;
+    getTokenCost({ intent, type, years, name, quantity, }: AoTokenCostParams): Promise<number>;
     getRegistrationFees(): Promise<AoRegistrationFees>;
     getDemandFactor(): Promise<number>;
     getDemandFactorSettings(): Promise<DemandFactorSettings>;
     getVaults(params?: PaginationParams<AoWalletVault>): Promise<PaginationResult<AoWalletVault>>;
-    getVault({ address, vaultId, }: {
-        address: WalletAddress;
-        vaultId: string;
-    }): Promise<AoVaultData>;
+    getVault({ address, vaultId, }: AoGetVaultParams): Promise<AoVaultData | undefined>;
     getPrimaryNameRequest(params: {
         initiator: WalletAddress;
     }): Promise<AoPrimaryNameRequest>;
@@ -355,7 +394,7 @@ export interface AoIORead {
         address: WalletAddress;
     } | {
         name: string;
-    }): Promise<AoPrimaryName>;
+    }): Promise<AoPrimaryName | undefined>;
     getPrimaryNames(params?: PaginationParams<AoPrimaryName>): Promise<PaginationResult<AoPrimaryName>>;
     getRedelegationFee(params: {
         address: WalletAddress;
@@ -393,23 +432,10 @@ export interface AoIOWrite extends AoIORead {
         reportTxId: TransactionId;
         failedGateways: WalletAddress[];
     }, options?: WriteOptions): Promise<AoMessageResult>;
-    buyRecord(params: {
-        name: string;
-        years?: number;
-        type: 'lease' | 'permabuy';
-        processId: string;
-    }, options?: WriteOptions): Promise<AoMessageResult>;
-    upgradeRecord(params: {
-        name: string;
-    }, options?: WriteOptions): Promise<AoMessageResult>;
-    extendLease(params: {
-        name: string;
-        years: number;
-    }, options?: WriteOptions): Promise<AoMessageResult>;
-    increaseUndernameLimit(params: {
-        name: string;
-        increaseCount: number;
-    }, options?: WriteOptions): Promise<AoMessageResult>;
+    buyRecord(params: AoBuyRecordParams, options?: WriteOptions): Promise<AoMessageResult>;
+    upgradeRecord(params: AoArNSNameParams, options?: WriteOptions): Promise<AoMessageResult>;
+    extendLease(params: AoExtendLeaseParams, options?: WriteOptions): Promise<AoMessageResult>;
+    increaseUndernameLimit(params: AoIncreaseUndernameLimitParams, options?: WriteOptions): Promise<AoMessageResult>;
     cancelWithdrawal(params: {
         gatewayAddress?: WalletAddress;
         vaultId: string;
@@ -424,12 +450,7 @@ export interface AoIOWrite extends AoIORead {
     requestPrimaryName(params: {
         name: string;
     }): Promise<AoMessageResult>;
-    redelegateStake(params: {
-        target: string;
-        source: string;
-        stakeQty: number | mIOToken;
-        vaultId?: string;
-    }, options?: WriteOptions): Promise<AoMessageResult>;
+    redelegateStake(params: AoRedelegateStakeParams, options?: WriteOptions): Promise<AoMessageResult>;
 }
 export declare function isProcessConfiguration(config: object): config is {
     process: AOProcess;

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

@@ -2,25 +2,29 @@ import Arweave from 'arweave';
 import { Logger } from '../common/index.js';
 import { AoANTRecord } from '../types/ant.js';
 import { AoClient, AoSigner, ContractSigner, WalletAddress } from '../types/index.js';
-export declare function spawnANT({ signer, module, luaCodeTxId, ao, scheduler, state, stateContractTxId, antRegistryId, logger, arweave, }: {
+export type SpawnANTState = {
+    owner: WalletAddress;
+    controllers: WalletAddress[];
+    name: string;
+    description: string;
+    keywords: string[];
+    ticker: string;
+    records: Record<string, AoANTRecord>;
+    balances: Record<WalletAddress, number>;
+};
+export type SpawnANTParams = {
     signer: AoSigner;
     module?: string;
     luaCodeTxId?: string;
     ao?: AoClient;
     scheduler?: string;
-    state?: {
-        owner: WalletAddress;
-        controllers: WalletAddress[];
-        name: string;
-        ticker: string;
-        records: Record<string, AoANTRecord>;
-        balances: Record<WalletAddress, number>;
-    };
+    state?: SpawnANTState;
     stateContractTxId?: string;
     antRegistryId?: string;
     logger?: Logger;
     arweave?: Arweave;
-}): Promise<string>;
+};
+export declare function spawnANT({ signer, module, luaCodeTxId, ao, scheduler, state, stateContractTxId, antRegistryId, logger, arweave, }: SpawnANTParams): Promise<string>;
 export declare function evolveANT({ signer, processId, luaCodeTxId, ao, logger, arweave, }: {
     signer: AoSigner;
     processId: string;
@@ -31,3 +35,9 @@ export declare function evolveANT({ signer, processId, luaCodeTxId, ao, logger,
 }): Promise<string>;
 export declare function isAoSigner(value: unknown): value is AoSigner;
 export declare function createAoSigner(signer: ContractSigner): AoSigner;
+export declare const defaultTargetManifestId = "-k7t8xMoB8hW482609Z9F4bTFMC3MnuW8bTvTyT8pFI";
+export declare function initANTStateForAddress({ owner, targetId, ttlSeconds, keywords, controllers, description, ticker, name, }: Partial<SpawnANTState> & {
+    targetId?: string;
+    ttlSeconds?: number;
+    owner: WalletAddress;
+}): SpawnANTState;

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 = "2.6.0-alpha.3";
+export declare const version = "2.6.0";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ar.io/sdk",
-  "version": "2.6.0-alpha.4",
+  "version": "2.7.0-alpha.1",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/ar-io/ar-io-sdk.git"
@@ -55,6 +55,9 @@
       "browser": "./bundles/web.bundle.min.js"
     }
   },
+  "bin": {
+    "ar.io": "./lib/esm/cli/cli.js"
+  },
   "scripts": {
     "build:web": "node bundle.mjs",
     "build:esm": "yarn tsc -p tsconfig.json",
@@ -89,6 +92,7 @@
     "@semantic-release/npm": "^11.0.3",
     "@trivago/prettier-plugin-sort-imports": "^4.2.0",
     "@types/node": "^20.12.12",
+    "@types/prompts": "^2.4.9",
     "@types/sinon": "^10.0.15",
     "@typescript-eslint/eslint-plugin": "^5.62.0",
     "@typescript-eslint/parser": "^6.4.0",
@@ -125,8 +129,10 @@
     "arweave": "1.14.4",
     "axios": "1.7.8",
     "axios-retry": "^4.3.0",
+    "commander": "^12.1.0",
     "eventemitter3": "^5.0.1",
     "plimit-lit": "^3.0.1",
+    "prompts": "^2.4.2",
     "winston": "^3.13.0",
     "zod": "^3.23.8"
   },