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

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

@@ -278,6 +278,11 @@ export declare const optionMap: {
         description: string;
         type: string;
     };
+    removeControllers: {
+        alias: string;
+        description: string;
+        type: string;
+    };
     lockLengthMs: {
         alias: string;
         description: string;

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

@@ -238,14 +238,20 @@ export declare class AoANTWriteable extends AoANTReadable implements AoANTWrite
     });
     /**
      * @param target @type {string} The address of the account you want to transfer the ANT to.
+     * @param removeControllers @type {boolean} Whether to remove the controllers of the ANT. Default is true.
+     * @example
+     * ```ts
+     * ant.transfer({ target: "fGht8v4STuwPnTck1zFVkQqJh5K9q9Zik4Y5-5dV7nk", removeControllers: false }); // will not remove the controllers of the ANT and just transfer ownership
+     * ```
      * @returns {Promise<AoMessageResult>} The result of the interaction.
      * @example
      * ```ts
      * ant.transfer({ target: "fGht8v4STuwPnTck1zFVkQqJh5K9q9Zik4Y5-5dV7nk" });
      * ```
      */
-    transfer({ target }: {
+    transfer({ target, removeControllers, }: {
         target: string;
+        removeControllers?: boolean;
     }, options?: WriteOptions): Promise<AoMessageResult>;
     /**
      * @param controller @type {string} The address of the account you want to set as a controller.

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

@@ -20,5 +20,6 @@ export * from './ant.js';
 export * from './ant-registry.js';
 export * from './ant-versions.js';
 export * from './faucet.js';
+export * from './marketplace.js';
 export * from './io.js';
 export * from './contracts/ao-process.js';

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

@@ -0,0 +1,434 @@
+/**
+ * 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 { AOProcess, AoSigner, Logger } from '../node/index.js';
+import { AoMessageResult, WalletAddress } from '../types/common.js';
+import { AoARIOWrite, PaginationParams, PaginationResult } from '../types/io.js';
+/**
+ * User-provided order parameters for intent-based order creation
+ * These are the user-configurable fields when creating an order via the intent workflow
+ */
+export interface MarketplaceOrderIntentParams {
+    orderType?: 'fixed' | 'dutch' | 'english';
+    quantity?: string;
+    price?: string;
+    expirationTime?: string;
+    minimumPrice?: string;
+    decreaseInterval?: string;
+}
+/**
+ * Intent structure - matches Lua Intent type
+ */
+export interface MarketplaceIntent {
+    intentId: string;
+    initiator: string;
+    action: string;
+    status: 'pending' | 'active' | 'settling' | 'completed' | 'resolved' | 'failed';
+    createdAt: number;
+    ttl?: number;
+    resolvedAt?: number;
+    completedAt?: number;
+    failureReason?: string;
+    orderParams: MarketplaceOrderIntentParams;
+    antProcessId: string;
+}
+/**
+ * Fee information structure for calculating order costs
+ */
+export interface MarketplaceFeeInfo {
+    listingFeePerHour: string;
+    saleTaxNumerator: number;
+    saleTaxDenominator: number;
+}
+/**
+ * Intent statistics structure
+ */
+export interface MarketplaceIntentStats {
+    total: number;
+    byStatus: Record<string, number>;
+    byType: Record<string, number>;
+    byAction: Record<string, number>;
+}
+/**
+ * Activity information structure
+ */
+export interface MarketplaceActivityInfo {
+    totalOrders: number;
+    activeOrders: number;
+    readyForSettlement: number;
+    executedOrders: number;
+    cancelledOrders: number;
+    expiredOrders: number;
+    listedOrders: number;
+}
+/**
+ * marketplace information structure
+ */
+export interface MarketplaceInfo {
+    totalPairs: number;
+    accruedFees: string;
+    arioTokenProcess: string;
+}
+/**
+ * Info response structure from the marketplace
+ */
+export interface InfoResponse {
+    name: string;
+    processId: string;
+    activity: MarketplaceActivityInfo;
+    intents: MarketplaceIntentStats;
+    ucm: MarketplaceInfo;
+    whitelistedModules: string[];
+    fees: MarketplaceFeeInfo;
+}
+/**
+ * Parameters for creating an intent (Create-Order action is assumed)
+ */
+export interface CreateIntentParams {
+    antId: string;
+    orderType: string;
+    quantity: string;
+    price: string;
+    expirationTime: string;
+    minimumPrice?: string;
+    decreaseInterval?: string;
+}
+/**
+ * Parameters for paginated intent queries
+ */
+export interface GetPaginatedIntentsParams {
+    cursor?: string;
+    limit?: number;
+    sortBy?: string;
+    sortOrder?: 'asc' | 'desc';
+    filters?: Record<string, string>;
+}
+/**
+ * Parameters for creating an order using internal ARIO balance
+ */
+export interface CreateOrderParams {
+    swapToken: string;
+    quantity: string;
+    orderType?: 'fixed' | 'dutch' | 'english';
+    price?: string;
+    expirationTime?: string;
+    minimumPrice?: string;
+    decreaseInterval?: string;
+    transferDenomination?: string;
+}
+/**
+ * Parameters for getting orders with flexible selectors
+ */
+export interface GetOrdersParams extends GetPaginatedIntentsParams {
+    status?: 'all' | 'listed' | 'completed' | 'active' | 'ready-for-settlement' | 'executed' | 'cancelled' | 'expired';
+    ids?: string[];
+    dominantToken?: string;
+    swapToken?: string;
+}
+/**
+ * Individual order structure returned from Get-Orders and Get-Order handlers
+ */
+export interface Order {
+    id: string;
+    creator: string;
+    quantity: string;
+    originalQuantity: string;
+    token: string;
+    dominantToken: string;
+    swapToken: string;
+    dateCreated: number;
+    price?: string;
+    expirationTime?: number;
+    orderType: 'fixed' | 'dutch' | 'english';
+    status: 'active' | 'executed' | 'cancelled' | 'ready-for-settlement' | 'expired';
+    minimumPrice?: string;
+    decreaseInterval?: string;
+    decreaseStep?: string;
+    sender?: string;
+    receiver?: string;
+    endedAt?: number;
+    bids?: Record<string, boolean>;
+}
+export interface MarketplaceBalance {
+    address: WalletAddress;
+    balance: string;
+    lockedBalance: string;
+    totalBalance: string;
+    orders: Record<string, string>;
+}
+export interface AoArNSMarketplaceRead {
+    getInfo(): Promise<InfoResponse>;
+    getPaginatedIntents(params: GetPaginatedIntentsParams): Promise<PaginationResult<MarketplaceIntent>>;
+    getIntent(intentId: string): Promise<MarketplaceIntent>;
+    getIntentByANTId(antId: string): Promise<MarketplaceIntent>;
+    getPaginatedOrders(params: GetOrdersParams): Promise<PaginationResult<Order>>;
+    getOrder(orderId: string): Promise<Order>;
+    getOrderByANTId(antId: string): Promise<Order>;
+    getPaginatedMarketplaceBalances(params: PaginationParams<MarketplaceBalance>): Promise<PaginationResult<MarketplaceBalance>>;
+    getMarketplaceBalance({ address, }: {
+        address: WalletAddress;
+    }): Promise<MarketplaceBalance>;
+    /**
+     * Get all user assets including intents, orders, balances, and ANT IDs
+     * @param params - Parameters including address and ARIO process ID
+     * @returns User assets including intents, orders, balances, and ANT IDs
+     */
+    getUserAssets({ address, arioProcessId, }: {
+        address: WalletAddress;
+        arioProcessId: string;
+    }): Promise<{
+        intents: MarketplaceIntent[];
+        orders: Order[];
+        balances: MarketplaceBalance;
+        antIds: string[];
+    }>;
+}
+export interface AoArNSMarketplaceWrite {
+    createIntent(params: CreateIntentParams): Promise<AoMessageResult<MarketplaceIntent>>;
+    cancelOrder(orderId: string): Promise<AoMessageResult>;
+    settleAuction(params: {
+        orderId: string;
+        dominantToken?: string;
+        swapToken?: string;
+    }): Promise<AoMessageResult>;
+    depositArIO(params: {
+        amount: string;
+    }): Promise<AoMessageResult>;
+    withdrawArIO(params: {
+        amount: string;
+    }): Promise<AoMessageResult>;
+    /**
+     * Push ANT intent resolution to the marketplace
+     * @param intentId - The intent ID to push resolution for
+     * @returns Message result
+     */
+    pushANTIntentResolution(intentId: string): Promise<AoMessageResult>;
+    /**
+     * List a name for sale on the marketplace
+     * @param params - Parameters including name, expiration time, price, type, wallet address, and optional auction parameters
+     * @returns Result containing intent, order, ANT transfer result, and any error
+     */
+    listNameForSale({ name, expirationTime, price, type, walletAddress, minimumPrice, decreaseInterval, }: {
+        name: string;
+        expirationTime: number;
+        price: string;
+        type: 'fixed' | 'dutch' | 'english';
+        walletAddress: WalletAddress;
+        minimumPrice?: string;
+        decreaseInterval?: string;
+    }): Promise<{
+        intent: MarketplaceIntent;
+        order: Order | null;
+        antTransferResult: AoMessageResult<Record<string, string | number | boolean | null>> | null;
+        error: Error | null;
+    }>;
+    /**
+     * Create an order using internal ARIO balance
+     * @param params - Order creation parameters
+     * @returns Message result with the created order
+     */
+    createOrder(params: CreateOrderParams): Promise<AoMessageResult<Order>>;
+    /**
+     * Buy a fixed price ANT
+     * @param params - Parameters including ANT ID
+     * @returns Message result with the order
+     */
+    buyFixedPriceANT(params: {
+        antId: string;
+    }): Promise<AoMessageResult<Order>>;
+    /**
+     * Buy a Dutch auction ANT
+     * @param params - Parameters including ANT ID
+     * @returns Message result with the order
+     */
+    buyDutchAuctionANT(params: {
+        antId: string;
+    }): Promise<AoMessageResult<Order>>;
+    /**
+     * Place a bid on an English auction
+     * @param params - Parameters including ANT ID and bid amount
+     * @returns Message result
+     */
+    bidOnANTEnglishAuction(params: {
+        antId: string;
+        bidAmount: string;
+    }): Promise<AoMessageResult>;
+    /**
+     * Settle an expired English auction
+     * @param params - Parameters including ANT ID
+     * @returns Message result
+     */
+    settleANTEnglishAuction(params: {
+        antId: string;
+    }): Promise<AoMessageResult>;
+}
+export declare class ArNSMarketplaceRead implements AoArNSMarketplaceRead {
+    protected process: AOProcess;
+    protected logger: Logger;
+    constructor({ process, logger, }: {
+        process: AOProcess;
+        logger?: Logger;
+    });
+    getInfo(): Promise<InfoResponse>;
+    getPaginatedIntents({ cursor, limit, sortBy, sortOrder, filters, }?: GetPaginatedIntentsParams): Promise<PaginationResult<MarketplaceIntent>>;
+    getIntent(intentId: string): Promise<MarketplaceIntent>;
+    getIntentByANTId(antId: string): Promise<MarketplaceIntent>;
+    /**
+     * Get orders with flexible selectors
+     * @param params - Parameters for filtering and pagination
+     * @returns Orders matching the criteria
+     */
+    getPaginatedOrders(params?: GetOrdersParams): Promise<PaginationResult<Order>>;
+    /**
+     * Get a single order by ID
+     * @param orderId - The order ID to fetch
+     * @returns The order if found
+     */
+    getOrder(orderId: string): Promise<Order>;
+    getOrderByANTId(antId: string): Promise<Order>;
+    getPaginatedMarketplaceBalances(params: PaginationParams<MarketplaceBalance>): Promise<PaginationResult<MarketplaceBalance>>;
+    /**
+     * Get ARIO balance for an address in the marketplace
+     */
+    getMarketplaceBalance({ address, }: {
+        address: WalletAddress;
+    }): Promise<MarketplaceBalance>;
+    getUserAssets({ address, arioProcessId, }: {
+        address: WalletAddress;
+        arioProcessId: string;
+    }): Promise<{
+        intents: MarketplaceIntent[];
+        orders: Order[];
+        balances: MarketplaceBalance;
+        antIds: string[];
+    }>;
+}
+export declare class ArNSMarketplaceWrite extends ArNSMarketplaceRead implements AoArNSMarketplaceWrite {
+    protected process: AOProcess;
+    protected signer: AoSigner;
+    protected ario: AoARIOWrite;
+    constructor({ process, signer, ario, logger, }: {
+        process: AOProcess;
+        signer: AoSigner;
+        ario: AoARIOWrite;
+        logger?: Logger;
+    });
+    /**
+     * Deposit ARIO to the marketplace (simulates Credit-Notice from ARIO token process)
+     * Returns the message ID for verification
+     */
+    depositArIO(params: {
+        amount: string;
+    }): Promise<AoMessageResult>;
+    /**
+     * Withdraw ARIO from the marketplace back to user
+     */
+    withdrawArIO(params: {
+        amount: string;
+    }): Promise<AoMessageResult>;
+    createIntent({ antId, orderType, quantity, price, expirationTime, minimumPrice, decreaseInterval, }: CreateIntentParams): Promise<AoMessageResult<MarketplaceIntent>>;
+    pushANTIntentResolution(intentId: string): Promise<AoMessageResult>;
+    settleAuction(params: {
+        orderId: string;
+        dominantToken?: string;
+        swapToken?: string;
+    }): Promise<AoMessageResult>;
+    listNameForSale({ name, expirationTime, price, type, walletAddress, minimumPrice, decreaseInterval, }: {
+        name: string;
+        expirationTime: number;
+        price: string;
+        type: 'fixed' | 'dutch' | 'english';
+        walletAddress: WalletAddress;
+        minimumPrice?: string;
+        decreaseInterval?: string;
+    }): Promise<{
+        intent: MarketplaceIntent;
+        order: Order | null;
+        antTransferResult: AoMessageResult<Record<string, string | number | boolean | null>> | null;
+        error: Error | null;
+    }>;
+    cancelOrder(orderId: string): Promise<AoMessageResult>;
+    createOrder({ swapToken, quantity, orderType, price, expirationTime, minimumPrice, decreaseInterval, transferDenomination, }: CreateOrderParams): Promise<AoMessageResult<Order>>;
+    buyFixedPriceANT(params: {
+        antId: string;
+    }): Promise<AoMessageResult<Order>>;
+    buyDutchAuctionANT(params: {
+        antId: string;
+    }): Promise<AoMessageResult<Order>>;
+    /**
+     * Place a bid on an English auction
+     * Note: This requires you to have sufficient ARIO balance in the marketplace
+     */
+    bidOnANTEnglishAuction(params: {
+        antId: string;
+        bidAmount: string;
+    }): Promise<AoMessageResult>;
+    /**
+     * Settle an expired English auction
+     * Can be called by anyone after the auction expires
+     * The highest bidder wins the ANT
+     */
+    settleANTEnglishAuction(params: {
+        antId: string;
+    }): Promise<AoMessageResult>;
+}
+/**
+ * Calculates the listing fee for an order based on the end timestamp.
+ * The fee is calculated by rounding up the hours until the end timestamp to the nearest hour.
+ *
+ * @param params - Parameters for calculating the listing fee
+ * @param params.listingFeePerHour - The listing fee per hour in mARIO (as a string)
+ * @param params.endTimestamp - Unix timestamp when the order expires
+ * @returns The listing fee in mARIO as a BigInt
+ *
+ * @example
+ * ```typescript
+ * const info = await marketplace.getInfo();
+ * const endTimestamp = Date.now() + 24 * 60 * 60 * 1000; // 24 hours from now
+ * const listingFee = calculateListingFee({
+ *   listingFeePerHour: info.fees.listingFeePerHour,
+ *   endTimestamp,
+ * });
+ * ```
+ */
+export declare function calculateListingFee({ listingFeePerHour, endTimestamp, }: {
+    listingFeePerHour: string;
+    endTimestamp: number;
+}): bigint;
+/**
+ * Calculates the sale tax for an order based on the sale amount.
+ *
+ * @param params - Parameters for calculating the sale tax
+ * @param params.saleAmount - The sale amount in mARIO (as a string or number)
+ * @param params.saleTaxNumerator - The numerator for sale tax calculation
+ * @param params.saleTaxDenominator - The denominator for sale tax calculation
+ * @returns The sale tax in mARIO as a BigInt
+ *
+ * @example
+ * ```typescript
+ * const info = await marketplace.getInfo();
+ * const saleAmount = 100000000000; // 100 ARIO in mARIO
+ * const tax = calculateSaleTax({
+ *   saleAmount,
+ *   saleTaxNumerator: info.fees.saleTaxNumerator,
+ *   saleTaxDenominator: info.fees.saleTaxDenominator,
+ * });
+ * ```
+ */
+export declare function calculateSaleTax({ saleAmount, saleTaxNumerator, saleTaxDenominator, }: {
+    saleAmount: string | number;
+    saleTaxNumerator: number;
+    saleTaxDenominator: number;
+}): bigint;

package/lib/types/constants.d.ts

@@ -22,6 +22,7 @@ export declare const ARIO_TESTNET_PROCESS_ID = "agYcCFJtrMG6cqMuZfskIkFTGvUPddIC
 export declare const ARIO_MAINNET_PROCESS_ID = "qNvAoz0TgcH7DMg8BCVn8jF32QH5L6T29VjHxhHqqGE";
 export declare const ANT_REGISTRY_TESTNET_ID = "RR0vheYqtsKuJCWh6xj0beE35tjaEug5cejMw9n2aa8";
 export declare const ANT_REGISTRY_ID = "i_le_yKKPVstLTDSmkHRqf-wYphMnwB9OhleiTgMkWc";
+export declare const MARKETPLACE_CONTRACT_ID = "wPh88ziUF4meLpHfffmgdA6IFtzmXHgdeg-epzBjkao";
 export declare const MARIO_PER_ARIO = 1000000;
 /**
  * @deprecated - use ANT.versions.getLatestANTVersion() to get latest ANT module

package/lib/types/types/ant.d.ts

@@ -362,6 +362,7 @@ export interface AoANTRead {
 export interface AoANTWrite extends AoANTRead {
     transfer: AoWriteAction<{
         target: WalletAddress;
+        removeControllers?: boolean;
     }>;
     addController: AoWriteAction<{
         controller: WalletAddress;

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ar.io/sdk",
-  "version": "3.22.0",
+  "version": "3.23.0-alpha.1",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/ar-io/ar-io-sdk.git"
@@ -68,7 +68,7 @@
     "test:cjs": "yarn build:cjs && yarn link && cd ./tests/e2e/cjs && yarn && yarn test",
     "test:esm": "yarn build:esm && yarn link && cd ./tests/e2e/esm && yarn && yarn test",
     "test:web": "yarn build:esm && yarn link && cd ./tests/e2e/web && yarn && yarn test",
-    "test:unit": "c8 node --import=./register.mjs --test --test-reporter=spec --enable-source-maps --trace-warnings 'src/**/*.test.ts'",
+    "test:unit": "c8 tsx --test --test-reporter=spec --enable-source-maps --trace-warnings 'src/**/*.test.ts'",
     "test:link": "yarn build && yarn link",
     "test:e2e": "yarn test:cjs && yarn test:esm && yarn test:web",
     "test:integration": "yarn build:esm && yarn link && cd ./tests/integration && yarn && yarn test",
@@ -96,11 +96,10 @@
     "@typescript-eslint/eslint-plugin": "^5.62.0",
     "@typescript-eslint/parser": "^6.4.0",
     "arconnect": "^1.0.3",
-    "axios": "^1.13.2",
     "c8": "^10.1.3",
     "dotenv": "^16.4.5",
     "dotenv-cli": "^7.4.2",
-    "esbuild": "^0.27.0",
+    "esbuild": "^0.27.1",
     "esbuild-plugin-polyfill-node": "^0.3.0",
     "eslint": "^8.47.0",
     "eslint-config-prettier": "^9.0.0",
@@ -122,12 +121,14 @@
     "sinon": "^15.2.0",
     "testcontainers": "^10.13.1",
     "ts-node": "^10.9.2",
+    "tsx": "^4.19.2",
     "typescript": "^5.1.6"
   },
   "dependencies": {
     "@dha-team/arbundles": "^1.0.1",
     "@permaweb/aoconnect": "0.0.68",
     "arweave": "1.15.5",
+    "axios": "^1.13.2",
     "commander": "^12.1.0",
     "eventemitter3": "^5.0.1",
     "prompts": "^2.4.2"