@ar.io/sdk 3.6.2-alpha.1 → 3.7.0-alpha.1

package/lib/esm/cli/cli.js

@@ -25,7 +25,7 @@ import { cancelWithdrawal, decreaseDelegateStake, decreaseOperatorStake, delegat
 import { getAllGatewayVaults, getAllowedDelegates, getArNSRecord, getArNSReservedName, getArNSReturnedName, getCostDetails, getDelegations, getEpoch, getGateway, getGatewayDelegates, getGatewayVaults, getPrescribedNames, getPrescribedObservers, getPrimaryName, getTokenCost, getVault, listAllDelegatesCLICommand, listArNSRecords, listArNSReservedNames, listArNSReturnedNames, listGateways, } from './commands/readCommands.js';
 import { createVaultCLICommand, extendVaultCLICommand, increaseVaultCLICommand, revokeVaultCLICommand, transferCLICommand, vaultedTransferCLICommand, } from './commands/transfer.js';
 import { addressAndVaultIdOptions, antStateOptions, arnsPurchaseOptions, buyRecordOptions, decreaseDelegateStakeOptions, delegateStakeOptions, epochOptions, getVaultOptions, globalOptions, joinNetworkOptions, operatorStakeOptions, optionMap, paginationAddressOptions, paginationOptions, redelegateStakeOptions, setAntBaseNameOptions, setAntUndernameOptions, tokenCostOptions, transferOptions, updateGatewaySettingsOptions, vaultedTransferOptions, writeActionOptions, } from './options.js';
-import { applyOptions, arioProcessIdFromOptions, assertConfirmationPrompt, epochInputFromOptions, formatARIOWithCommas, getANTStateFromOptions, getLoggerFromOptions, makeCommand, paginationParamsFromOptions, readANTFromOptions, readARIOFromOptions, requiredAddressFromOptions, requiredAoSignerFromOptions, requiredProcessIdFromOptions, requiredStringArrayFromOptions, requiredStringFromOptions, writeANTFromOptions, writeActionTagsFromOptions, } from './utils.js';
+import { applyOptions, arioProcessIdFromOptions, assertConfirmationPrompt, customTagsFromOptions, epochInputFromOptions, formatARIOWithCommas, getANTStateFromOptions, getLoggerFromOptions, makeCommand, paginationParamsFromOptions, readANTFromOptions, readARIOFromOptions, requiredAddressFromOptions, requiredAoSignerFromOptions, requiredProcessIdFromOptions, requiredStringArrayFromOptions, requiredStringFromOptions, writeANTFromOptions, } from './utils.js';
 applyOptions(program
     .name('ar.io')
     .version(version)
@@ -51,6 +51,16 @@ makeCommand({
     description: 'Get demand factor',
     action: (options) => readARIOFromOptions(options).getDemandFactor(),
 });
+makeCommand({
+    name: 'get-demand-factor-settings',
+    description: 'Get current settings for demand factor',
+    action: (options) => readARIOFromOptions(options).getDemandFactorSettings(),
+});
+makeCommand({
+    name: 'get-epoch-settings',
+    description: 'Get current settings for epochs',
+    action: (options) => readARIOFromOptions(options).getEpochSettings(),
+});
 makeCommand({
     name: 'get-gateway',
     description: 'Get the gateway of an address',
@@ -162,6 +172,14 @@ makeCommand({
         .getDistributions(epochInputFromOptions(o))
         .then((result) => result ?? { message: 'No distributions found for epoch' }),
 });
+makeCommand({
+    name: 'get-eligible-rewards',
+    description: 'Get eligible rewards for an epoch',
+    options: [...epochOptions, ...paginationOptions],
+    action: (o) => readARIOFromOptions(o)
+        .getEligibleEpochRewards(epochInputFromOptions(o), paginationParamsFromOptions(o))
+        .then((result) => result ?? { message: 'No eligible distributions found for epoch' }),
+});
 makeCommand({
     name: 'get-token-cost',
     description: 'Get token cost for an intended action',
@@ -509,7 +527,7 @@ makeCommand({
         await assertConfirmationPrompt(`Are you sure you want to transfer ANT ownership to ${target}?`, options);
         return writeANTFromOptions(options).transfer({
             target,
-        }, writeActionTagsFromOptions(options));
+        }, customTagsFromOptions(options));
     },
 });
 makeCommand({
@@ -521,7 +539,7 @@ makeCommand({
         await assertConfirmationPrompt(`Are you sure you want to add ${controller} as a controller?`, options);
         return writeANTFromOptions(options).addController({
             controller: requiredStringFromOptions(options, 'controller'),
-        }, writeActionTagsFromOptions(options));
+        }, customTagsFromOptions(options));
     },
 });
 makeCommand({
@@ -531,7 +549,7 @@ makeCommand({
     action: async (options) => {
         return writeANTFromOptions(options).removeController({
             controller: requiredStringFromOptions(options, 'controller'),
-        }, writeActionTagsFromOptions(options));
+        }, customTagsFromOptions(options));
     },
 });
 makeCommand({
@@ -561,7 +579,7 @@ makeCommand({
         await assertConfirmationPrompt(`Are you sure you want to remove the record with undername ${undername}?`, options);
         return writeANTFromOptions(options).removeRecord({
             undername,
-        }, writeActionTagsFromOptions(options));
+        }, customTagsFromOptions(options));
     },
 });
 makeCommand({
@@ -573,7 +591,7 @@ makeCommand({
         await assertConfirmationPrompt(`Are you sure you want to set the ticker to ${ticker}?`, options);
         return writeANTFromOptions(options).setTicker({
             ticker,
-        }, writeActionTagsFromOptions(options));
+        }, customTagsFromOptions(options));
     },
 });
 makeCommand({
@@ -585,7 +603,7 @@ makeCommand({
         await assertConfirmationPrompt(`Are you sure you want to set the name to ${requiredStringFromOptions(options, 'name')}?`, options);
         return writeANTFromOptions(options).setName({
             name,
-        }, writeActionTagsFromOptions(options));
+        }, customTagsFromOptions(options));
     },
 });
 makeCommand({
@@ -597,7 +615,7 @@ makeCommand({
         await assertConfirmationPrompt(`Are you sure you want to set the ANT description to ${description}?`, options);
         return writeANTFromOptions(options).setDescription({
             description,
-        }, writeActionTagsFromOptions(options));
+        }, customTagsFromOptions(options));
     },
 });
 makeCommand({
@@ -609,7 +627,7 @@ makeCommand({
         await assertConfirmationPrompt(`Are you sure you want to set the ANT keywords to ${keywords}?`, options);
         return writeANTFromOptions(options).setKeywords({
             keywords,
-        }, writeActionTagsFromOptions(options));
+        }, customTagsFromOptions(options));
     },
 });
 makeCommand({
@@ -626,7 +644,7 @@ makeCommand({
         return writeANTFromOptions(options).setLogo({
             // TODO: Could take a logo file, upload it to Arweave, get transaction ID
             txId,
-        }, writeActionTagsFromOptions(options));
+        }, customTagsFromOptions(options));
     },
 });
 makeCommand({
@@ -639,7 +657,7 @@ makeCommand({
         return writeANTFromOptions(options).releaseName({
             name,
             arioProcessId: arioProcessIdFromOptions(options),
-        }, writeActionTagsFromOptions(options));
+        }, customTagsFromOptions(options));
     },
 });
 makeCommand({
@@ -659,7 +677,7 @@ makeCommand({
             name,
             arioProcessId: arioProcessIdFromOptions(options),
             antProcessId: targetProcess,
-        }, writeActionTagsFromOptions(options));
+        }, customTagsFromOptions(options));
     },
 });
 makeCommand({
@@ -679,7 +697,7 @@ makeCommand({
             name,
             address,
             arioProcessId: arioProcessIdFromOptions(options),
-        }, writeActionTagsFromOptions(options));
+        }, customTagsFromOptions(options));
     },
 });
 makeCommand({
@@ -692,7 +710,7 @@ makeCommand({
         return writeANTFromOptions(options).removePrimaryNames({
             names,
             arioProcessId: arioProcessIdFromOptions(options),
-        }, writeActionTagsFromOptions(options));
+        }, customTagsFromOptions(options));
     },
 });
 makeCommand({
@@ -705,11 +723,25 @@ makeCommand({
             logger: getLoggerFromOptions(options),
         });
         return process.send({
-            tags: writeActionTagsFromOptions(options).tags ?? [],
+            tags: customTagsFromOptions(options).tags ?? [],
             signer: requiredAoSignerFromOptions(options),
         });
     },
 });
+makeCommand({
+    name: 'read-action',
+    description: 'Send a dry-run read action to an AO Process',
+    options: [optionMap.processId, optionMap.tags],
+    action: async (options) => {
+        const process = new AOProcess({
+            processId: requiredProcessIdFromOptions(options),
+            logger: getLoggerFromOptions(options),
+        });
+        return process.read({
+            tags: customTagsFromOptions(options).tags ?? [],
+        });
+    },
+});
 if (process.argv[1].includes('bin/ar.io') || // Running from global .bin
     process.argv[1].includes('cli/cli') // Running from source
 ) {

package/lib/esm/cli/commands/antCommands.js

@@ -1,4 +1,4 @@
-import { assertConfirmationPrompt, defaultTtlSecondsCLI, requiredStringFromOptions, writeANTFromOptions, writeActionTagsFromOptions, } from '../utils.js';
+import { assertConfirmationPrompt, customTagsFromOptions, defaultTtlSecondsCLI, requiredStringFromOptions, writeANTFromOptions, } from '../utils.js';
 /** @deprecated -- use set-ant-base-name and set-ant-undername */
 export async function setAntRecordCLICommand(o) {
     const ttlSeconds = +(o.ttlSeconds ?? defaultTtlSecondsCLI);
@@ -12,7 +12,7 @@ export async function setAntRecordCLICommand(o) {
         undername,
         transactionId,
         ttlSeconds,
-    }, writeActionTagsFromOptions(o));
+    }, customTagsFromOptions(o));
 }
 export async function setAntBaseNameCLICommand(o) {
     const ttlSeconds = +(o.ttlSeconds ?? defaultTtlSecondsCLI);
@@ -24,7 +24,7 @@ export async function setAntBaseNameCLICommand(o) {
     return writeANTFromOptions(o).setBaseNameRecord({
         transactionId,
         ttlSeconds,
-    }, writeActionTagsFromOptions(o));
+    }, customTagsFromOptions(o));
 }
 export async function setAntUndernameCLICommand(o) {
     const ttlSeconds = +(o.ttlSeconds ?? defaultTtlSecondsCLI);
@@ -38,5 +38,5 @@ export async function setAntUndernameCLICommand(o) {
         undername,
         transactionId,
         ttlSeconds,
-    }, writeActionTagsFromOptions(o));
+    }, customTagsFromOptions(o));
 }

package/lib/esm/cli/commands/arnsPurchaseCommands.js

@@ -1,4 +1,4 @@
-import { assertConfirmationPrompt, assertEnoughBalanceForArNSPurchase, fundFromFromOptions, positiveIntegerFromOptions, recordTypeFromOptions, requiredPositiveIntegerFromOptions, requiredStringFromOptions, writeARIOFromOptions, writeActionTagsFromOptions, } from '../utils.js';
+import { assertConfirmationPrompt, assertEnoughBalanceForArNSPurchase, customTagsFromOptions, fundFromFromOptions, positiveIntegerFromOptions, recordTypeFromOptions, requiredPositiveIntegerFromOptions, requiredStringFromOptions, writeARIOFromOptions, } from '../utils.js';
 export async function buyRecordCLICommand(o) {
     const { ario, signerAddress } = writeARIOFromOptions(o);
     const name = requiredStringFromOptions(o, 'name');
@@ -37,7 +37,7 @@ export async function buyRecordCLICommand(o) {
         type,
         years,
         fundFrom: fundFromFromOptions(o),
-    }, writeActionTagsFromOptions(o));
+    }, customTagsFromOptions(o));
 }
 export async function upgradeRecordCLICommand(o) {
     const name = requiredStringFromOptions(o, 'name');
@@ -101,7 +101,7 @@ export async function extendLeaseCLICommand(o) {
     return ario.extendLease({
         name,
         years,
-    }, writeActionTagsFromOptions(o));
+    }, customTagsFromOptions(o));
 }
 export async function increaseUndernameLimitCLICommand(o) {
     const name = requiredStringFromOptions(o, 'name');
@@ -131,7 +131,7 @@ export async function increaseUndernameLimitCLICommand(o) {
     return ario.increaseUndernameLimit({
         name,
         increaseCount,
-    }, writeActionTagsFromOptions(o));
+    }, customTagsFromOptions(o));
 }
 export async function requestPrimaryNameCLICommand(o) {
     const { ario, signerAddress } = writeARIOFromOptions(o);
@@ -155,5 +155,5 @@ export async function requestPrimaryNameCLICommand(o) {
     return ario.requestPrimaryName({
         name,
         fundFrom,
-    }, writeActionTagsFromOptions(o));
+    }, customTagsFromOptions(o));
 }

package/lib/esm/cli/commands/gatewayWriteCommands.js

@@ -15,7 +15,7 @@
  */
 import prompts from 'prompts';
 import { mARIOToken } from '../../node/index.js';
-import { assertConfirmationPrompt, assertEnoughMARIOBalance, formatARIOWithCommas, gatewaySettingsFromOptions, redelegateParamsFromOptions, requiredAddressFromOptions, requiredMARIOFromOptions, requiredStringArrayFromOptions, requiredStringFromOptions, requiredTargetAndQuantityFromOptions, stringifyJsonForCLIDisplay, writeARIOFromOptions, writeActionTagsFromOptions, } from '../utils.js';
+import { assertConfirmationPrompt, assertEnoughMARIOBalance, customTagsFromOptions, formatARIOWithCommas, gatewaySettingsFromOptions, redelegateParamsFromOptions, requiredAddressFromOptions, requiredMARIOFromOptions, requiredStringArrayFromOptions, requiredStringFromOptions, requiredTargetAndQuantityFromOptions, stringifyJsonForCLIDisplay, writeARIOFromOptions, } from '../utils.js';
 export async function joinNetwork(options) {
     const { ario, signerAddress } = writeARIOFromOptions(options);
     const mARIOQuantity = requiredMARIOFromOptions(options, 'operatorStake');
@@ -41,7 +41,7 @@ export async function joinNetwork(options) {
         });
         await assertConfirmationPrompt(`Gateway Settings:\n\n${JSON.stringify(settings, null, 2)}\n\nYou are about to stake ${formatARIOWithCommas(mARIOQuantity.toARIO())} ARIO to join the AR.IO network\nAre you sure?\n`, options);
     }
-    const result = await ario.joinNetwork(settings, writeActionTagsFromOptions(options));
+    const result = await ario.joinNetwork(settings, customTagsFromOptions(options));
     const output = {
         joinNetworkResult: result,
         joinedAddress: signerAddress,
@@ -57,7 +57,7 @@ export async function updateGatewaySettings(options) {
         throw new Error('No gateway settings provided');
     }
     await assertConfirmationPrompt(`Gateway Settings:\n\n${stringifyJsonForCLIDisplay(gatewaySettings)}\n\nYou are about to update your gateway settings to the above\nAre you sure?\n`, options);
-    const result = await ario.updateGatewaySettings(gatewaySettings, writeActionTagsFromOptions(options));
+    const result = await ario.updateGatewaySettings(gatewaySettings, customTagsFromOptions(options));
     const output = {
         updateGatewaySettingsResult: result,
         updatedGatewayAddress: signerAddress,
@@ -77,7 +77,7 @@ export async function leaveNetwork(options) {
             '\n\n' +
             'Are you sure you want to leave the AR.IO network?', options);
     }
-    return writeARIOFromOptions(options).ario.leaveNetwork(writeActionTagsFromOptions(options));
+    return writeARIOFromOptions(options).ario.leaveNetwork(customTagsFromOptions(options));
 }
 export async function saveObservations(o) {
     const failedGateways = requiredStringArrayFromOptions(o, 'failedGateways');
@@ -86,7 +86,7 @@ export async function saveObservations(o) {
     return writeARIOFromOptions(o).ario.saveObservations({
         failedGateways: requiredStringArrayFromOptions(o, 'failedGateways'),
         reportTxId: requiredStringFromOptions(o, 'transactionId'),
-    }, writeActionTagsFromOptions(o));
+    }, customTagsFromOptions(o));
 }
 export async function increaseOperatorStake(o) {
     const increaseQty = requiredMARIOFromOptions(o, 'operatorStake');
@@ -94,7 +94,7 @@ export async function increaseOperatorStake(o) {
     return (writeARIOFromOptions(o).ario.increaseOperatorStake({
         increaseQty,
     }),
-        writeActionTagsFromOptions(o));
+        customTagsFromOptions(o));
 }
 export async function decreaseOperatorStake(o) {
     const decreaseQty = requiredMARIOFromOptions(o, 'operatorStake');
@@ -102,7 +102,7 @@ export async function decreaseOperatorStake(o) {
     await assertConfirmationPrompt(`You are about to decrease your operator stake by ${formatARIOWithCommas(decreaseQty.toARIO())} ARIO\nAre you sure?`, o);
     return writeARIOFromOptions(o).ario.decreaseOperatorStake({
         decreaseQty,
-    }, writeActionTagsFromOptions(o));
+    }, customTagsFromOptions(o));
 }
 export async function instantWithdrawal(o) {
     const vaultId = requiredStringFromOptions(o, 'vaultId');
@@ -111,7 +111,7 @@ export async function instantWithdrawal(o) {
     return writeARIOFromOptions(o).ario.instantWithdrawal({
         vaultId,
         gatewayAddress,
-    }, writeActionTagsFromOptions(o));
+    }, customTagsFromOptions(o));
 }
 export async function cancelWithdrawal(o) {
     const vaultId = requiredStringFromOptions(o, 'vaultId');
@@ -120,7 +120,7 @@ export async function cancelWithdrawal(o) {
     return writeARIOFromOptions(o).ario.cancelWithdrawal({
         vaultId,
         gatewayAddress,
-    }, writeActionTagsFromOptions(o));
+    }, customTagsFromOptions(o));
 }
 export async function delegateStake(options) {
     const { ario, signerAddress } = writeARIOFromOptions(options);
@@ -152,7 +152,7 @@ export async function delegateStake(options) {
     const result = await ario.delegateStake({
         target,
         stakeQty: arioQuantity.toMARIO(),
-    }, writeActionTagsFromOptions(options));
+    }, customTagsFromOptions(options));
     const output = {
         senderAddress: signerAddress,
         transferResult: result,

package/lib/esm/cli/commands/transfer.js

@@ -1,4 +1,4 @@
-import { assertEnoughMARIOBalance, assertLockLengthInRange, confirmationPrompt, formatARIOWithCommas, formatMARIOToARIOWithCommas, requiredMARIOFromOptions, requiredPositiveIntegerFromOptions, requiredStringFromOptions, requiredTargetAndQuantityFromOptions, writeARIOFromOptions, writeActionTagsFromOptions, } from '../utils.js';
+import { assertEnoughMARIOBalance, assertLockLengthInRange, confirmationPrompt, customTagsFromOptions, formatARIOWithCommas, formatMARIOToARIOWithCommas, requiredMARIOFromOptions, requiredPositiveIntegerFromOptions, requiredStringFromOptions, requiredTargetAndQuantityFromOptions, writeARIOFromOptions, } from '../utils.js';
 export async function transferCLICommand(options) {
     const { target, arioQuantity } = requiredTargetAndQuantityFromOptions(options);
     const { ario, signerAddress } = writeARIOFromOptions(options);
@@ -16,7 +16,7 @@ export async function transferCLICommand(options) {
     const result = await ario.transfer({
         target,
         qty: arioQuantity.toMARIO().valueOf(),
-    }, writeActionTagsFromOptions(options));
+    }, customTagsFromOptions(options));
     const output = {
         senderAddress: signerAddress,
         transferResult: result,
@@ -46,7 +46,7 @@ export async function vaultedTransferCLICommand(o) {
         quantity: mARIOQuantity,
         lockLengthMs,
         revokable: o.revokable,
-    }, writeActionTagsFromOptions(o));
+    }, customTagsFromOptions(o));
     const output = {
         senderAddress: signerAddress,
         transferResult: result,
@@ -71,7 +71,7 @@ export async function revokeVaultCLICommand(o) {
     const result = await ario.revokeVault({
         vaultId,
         recipient,
-    }, writeActionTagsFromOptions(o));
+    }, customTagsFromOptions(o));
     const output = {
         senderAddress: signerAddress,
         transferResult: result,
@@ -98,7 +98,7 @@ export async function createVaultCLICommand(o) {
     const result = await ario.createVault({
         quantity: mARIOQuantity,
         lockLengthMs,
-    }, writeActionTagsFromOptions(o));
+    }, customTagsFromOptions(o));
     const output = {
         senderAddress: signerAddress,
         transferResult: result,
@@ -124,7 +124,7 @@ export async function extendVaultCLICommand(o) {
     const result = await ario.extendVault({
         vaultId,
         extendLengthMs,
-    }, writeActionTagsFromOptions(o));
+    }, customTagsFromOptions(o));
     const output = {
         senderAddress: signerAddress,
         transferResult: result,
@@ -149,7 +149,7 @@ export async function increaseVaultCLICommand(o) {
     const result = await ario.increaseVault({
         vaultId,
         quantity: mARIOQuantity,
-    }, writeActionTagsFromOptions(o));
+    }, customTagsFromOptions(o));
     const output = {
         senderAddress: signerAddress,
         transferResult: result,

package/lib/esm/cli/utils.js

@@ -204,7 +204,7 @@ export function requiredInitiatorFromOptions(options) {
     }
     return requiredAddressFromOptions(options);
 }
-export function writeActionTagsFromOptions(options) {
+export function customTagsFromOptions(options) {
     if (options.tags === undefined) {
         return {};
     }

package/lib/esm/common/io.js

@@ -1,7 +1,7 @@
 import { ARIO_TESTNET_PROCESS_ID } from '../constants.js';
 import { isProcessConfiguration, isProcessIdConfiguration, } from '../types/io.js';
 import { createAoSigner } from '../utils/ao.js';
-import { getEpochDataFromGql, paginationParamsToTags, pruneTags, } from '../utils/arweave.js';
+import { getEpochDataFromGql, paginationParamsToTags, pruneTags, removeEligibleRewardsFromEpochData, sortAndPaginateEpochDataIntoEligibleDistributions, } from '../utils/arweave.js';
 import { defaultArweave } from './arweave.js';
 import { AOProcess } from './contracts/ao-process.js';
 import { InvalidContractConfigurationError } from './error.js';
@@ -85,7 +85,7 @@ export class ARIOReadable {
                 epochIndex: epochIndex,
                 processId: this.process.processId,
             });
-            return epochData;
+            return removeEligibleRewardsFromEpochData(epochData);
         }
         // go to the process epoch and fetch the epoch data
         const allTags = [
@@ -294,6 +294,26 @@ export class ARIOReadable {
             tags: pruneTags(allTags),
         });
     }
+    async getEligibleEpochRewards(epoch, params) {
+        const epochIndex = await this.computeEpochIndex(epoch);
+        const currentIndex = await this.computeCurrentEpochIndex();
+        if (epochIndex !== undefined && epochIndex < currentIndex) {
+            const epochData = await getEpochDataFromGql({
+                arweave: this.arweave,
+                epochIndex: epochIndex,
+                processId: this.process.processId,
+            });
+            return sortAndPaginateEpochDataIntoEligibleDistributions(epochData, params);
+        }
+        // on current epoch, go to process and fetch the distributions
+        const allTags = [
+            { name: 'Action', value: 'Epoch-Eligible-Rewards' },
+            ...paginationParamsToTags(params),
+        ];
+        return this.process.read({
+            tags: pruneTags(allTags),
+        });
+    }
     async getTokenCost({ intent, type, years, name, quantity, fromAddress, }) {
         const replacedBuyRecordWithBuyName = intent === 'Buy-Record' ? 'Buy-Name' : intent;
         const allTags = [

package/lib/esm/types/io.js

@@ -1,4 +1,12 @@
 import { validateArweaveId } from '../utils/arweave.js';
+export const isDistributedEpochData = (data) => {
+    return data.distributedTimestamp !== undefined;
+};
+export const isDistributedEpoch = (data) => {
+    return (data !== undefined &&
+        data.distributions !== undefined &&
+        isDistributedEpochData(data.distributions));
+};
 export const validIntents = [
     'Buy-Name',
     'Buy-Record', // for backwards compatibility

package/lib/esm/utils/arweave.js

@@ -1,4 +1,5 @@
 import { ARIO_TESTNET_PROCESS_ID, ARWEAVE_TX_REGEX } from '../constants.js';
+import { isDistributedEpoch, } from '../types/io.js';
 import { parseAoEpochData } from './ao.js';
 export const validateArweaveId = (id) => {
     return ARWEAVE_TX_REGEX.test(id);
@@ -94,3 +95,83 @@ export const epochDistributionNoticeGqlQuery = ({ epochIndex, processId = ARIO_T
     });
     return gqlQuery;
 };
+export function sortAndPaginateEpochDataIntoEligibleDistributions(epochData, params) {
+    const rewards = [];
+    const sortBy = params?.sortBy ?? 'eligibleReward';
+    const sortOrder = params?.sortOrder ?? 'desc';
+    const limit = params?.limit ?? 100;
+    if (!isDistributedEpoch(epochData)) {
+        return {
+            hasMore: false,
+            items: [],
+            totalItems: 0,
+            limit,
+            sortOrder,
+            sortBy,
+        };
+    }
+    const eligibleDistributions = epochData?.distributions.rewards.eligible;
+    for (const [gatewayAddress, reward] of Object.entries(eligibleDistributions)) {
+        rewards.push({
+            type: 'operatorReward',
+            recipient: gatewayAddress,
+            eligibleReward: reward.operatorReward,
+            cursorId: gatewayAddress + '_' + gatewayAddress,
+            gatewayAddress,
+        });
+        for (const [delegateAddress, delegateRewardQty] of Object.entries(reward.delegateRewards)) {
+            rewards.push({
+                type: 'delegateReward',
+                recipient: delegateAddress,
+                eligibleReward: delegateRewardQty,
+                cursorId: gatewayAddress + '_' + delegateAddress,
+                gatewayAddress,
+            });
+        }
+    }
+    // sort the rewards by the sortBy
+    rewards.sort((a, b) => {
+        const aSort = a[sortBy];
+        const bSort = b[sortBy];
+        if (aSort === bSort || aSort === undefined || bSort === undefined) {
+            return 0;
+        }
+        if (sortOrder === 'asc') {
+            return aSort > bSort ? 1 : -1;
+        }
+        return aSort < bSort ? 1 : -1;
+    });
+    // paginate the rewards
+    const start = params?.cursor !== undefined
+        ? rewards.findIndex((r) => r.cursorId === params.cursor) + 1
+        : 0;
+    const end = limit ? start + limit : rewards.length;
+    return {
+        hasMore: end < rewards.length,
+        items: rewards.slice(start, end),
+        totalItems: rewards.length,
+        limit,
+        sortOrder,
+        nextCursor: rewards[end]?.cursorId,
+        sortBy,
+    };
+}
+export function removeEligibleRewardsFromEpochData(epochData) {
+    if (epochData === undefined) {
+        return undefined;
+    }
+    if (!isDistributedEpoch(epochData)) {
+        return epochData;
+    }
+    return {
+        ...epochData,
+        distributions: {
+            ...epochData.distributions,
+            rewards: {
+                ...epochData.distributions.rewards,
+                // @ts-expect-error -- remove eligible rewards
+                eligible: undefined,
+            },
+        },
+    };
+}

package/lib/esm/utils/utils.test.js

@@ -1,6 +1,6 @@
 import { strict as assert } from 'node:assert';
 import { describe, it } from 'node:test';
-import { pruneTags } from './arweave.js';
+import { pruneTags, sortAndPaginateEpochDataIntoEligibleDistributions, } from './arweave.js';
 import { errorMessageFromOutput } from './index.js';
 describe('pruneTags', () => {
     it('should remove tags with undefined values', () => {
@@ -102,3 +102,101 @@ describe('errorMessageFromOutput', () => {
         assert.equal(errorMessage, 'Already registered (line 128)');
     });
 });
+describe('sortAndPaginateEpochDataIntoEligibleDistributions', () => {
+    const mockEpochData = {
+        distributions: {
+            distributedTimestamp: 1234567890,
+            rewards: {
+                eligible: {
+                    gateway1: {
+                        operatorReward: 50,
+                        delegateRewards: {
+                            delegate1: 20,
+                            delegate2: 30,
+                        },
+                    },
+                    gateway2: {
+                        operatorReward: 70,
+                        delegateRewards: {
+                            delegate3: 40,
+                        },
+                    },
+                },
+            },
+        },
+    };
+    it('returns empty results when epochData is undefined', () => {
+        assert.deepEqual(sortAndPaginateEpochDataIntoEligibleDistributions(undefined), {
+            hasMore: false,
+            items: [],
+            totalItems: 0,
+            limit: 100,
+            sortOrder: 'desc',
+            sortBy: 'eligibleReward',
+        });
+    });
+    it('sorts rewards in descending order by eligibleReward', () => {
+        const result = sortAndPaginateEpochDataIntoEligibleDistributions(mockEpochData);
+        assert.deepEqual(result.items, [
+            {
+                type: 'operatorReward',
+                recipient: 'gateway2',
+                eligibleReward: 70,
+                cursorId: 'gateway2_gateway2',
+                gatewayAddress: 'gateway2',
+            },
+            {
+                type: 'operatorReward',
+                recipient: 'gateway1',
+                eligibleReward: 50,
+                cursorId: 'gateway1_gateway1',
+                gatewayAddress: 'gateway1',
+            },
+            {
+                type: 'delegateReward',
+                recipient: 'delegate3',
+                eligibleReward: 40,
+                cursorId: 'gateway2_delegate3',
+                gatewayAddress: 'gateway2',
+            },
+            {
+                type: 'delegateReward',
+                recipient: 'delegate2',
+                eligibleReward: 30,
+                cursorId: 'gateway1_delegate2',
+                gatewayAddress: 'gateway1',
+            },
+            {
+                type: 'delegateReward',
+                recipient: 'delegate1',
+                eligibleReward: 20,
+                cursorId: 'gateway1_delegate1',
+                gatewayAddress: 'gateway1',
+            },
+        ]);
+    });
+    it('supports sorting in ascending order', () => {
+        const result = sortAndPaginateEpochDataIntoEligibleDistributions(mockEpochData, {
+            sortOrder: 'asc',
+        });
+        assert.equal(result.items[0].eligibleReward, 20);
+        assert.equal(result.items[result.items.length - 1].eligibleReward, 70);
+    });
+    it('paginates results correctly', () => {
+        const result = sortAndPaginateEpochDataIntoEligibleDistributions(mockEpochData, {
+            limit: 2,
+        });
+        assert.equal(result.items.length, 2);
+        assert.equal(result.hasMore, true);
+        assert.equal(result.nextCursor, 'gateway2_delegate3');
+    });
+    it('resumes pagination from cursor', () => {
+        const firstPage = sortAndPaginateEpochDataIntoEligibleDistributions(mockEpochData, { limit: 2 });
+        const secondPage = sortAndPaginateEpochDataIntoEligibleDistributions(mockEpochData, {
+            limit: 2,
+            cursor: firstPage.nextCursor,
+        });
+        assert.equal(secondPage.items.length, 2);
+        assert.equal(secondPage.items[0].cursorId, 'gateway1_delegate2');
+    });
+});

package/lib/esm/version.js

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