chore: release v2.5.0

CHANGELOG.md

@@ -1,3 +1,34 @@
+# [2.5.0-alpha.3](https://github.com/ar-io/ar-io-sdk/compare/v2.5.0-alpha.2...v2.5.0-alpha.3) (2024-11-14)
+
+
+### Bug Fixes
+
+* **io:** add `getDelegations` to `AoIORead` ([7c30c9b](https://github.com/ar-io/ar-io-sdk/commit/7c30c9b6dda8014575ba4f34f59fc4844c0ffe7a))
+* **types:** modify AoDelegation type ([18bb755](https://github.com/ar-io/ar-io-sdk/commit/18bb755c8a688060ea19ae9711888d0d53f1041f))
+
+# [2.5.0-alpha.2](https://github.com/ar-io/ar-io-sdk/compare/v2.5.0-alpha.1...v2.5.0-alpha.2) (2024-11-14)
+
+
+### Bug Fixes
+
+* **id and test:** add test for old ant and add lua source id for new code ([77601b2](https://github.com/ar-io/ar-io-sdk/commit/77601b2fc9117a2a4b9ff1226fa3f329e8a74e1d))
+* **tests:** add test for old ant ([0489cb6](https://github.com/ar-io/ar-io-sdk/commit/0489cb6924b68c19b8791cc47e0f7c1589be842f))
+* **tests:** add unit tests for util and move parsing of records to uitl ([2d08c9a](https://github.com/ar-io/ar-io-sdk/commit/2d08c9a18f1916db3d64be5af494fb4013b347c5))
+* **tests:** update ANT in tests to use v8 ant ([1eff8a9](https://github.com/ar-io/ar-io-sdk/commit/1eff8a97ab7179fb1d4e0ff68924480f360ee52c))
+
+
+### Features
+
+* **getRecords:** update getRecords to return as flat array of objects ([b9808c1](https://github.com/ar-io/ar-io-sdk/commit/b9808c117cd55a1ce92eb338a07fc07395a867fd))
+
+# [2.5.0-alpha.1](https://github.com/ar-io/ar-io-sdk/compare/v2.4.0...v2.5.0-alpha.1) (2024-11-14)
+
+
+### Features
+
+* **delegations:** add getter for staked and vaulted delegations PE-7093 ([7182942](https://github.com/ar-io/ar-io-sdk/commit/7182942ca737f86e94dc35423c71cd2bc6412f1d))
+* **delegations:** add SDK function to retrieve an address's delegations PE-7093 ([07c9107](https://github.com/ar-io/ar-io-sdk/commit/07c910786d4fd4d95b463a9eb28121149e66eb8a))
+
 # [2.4.0](https://github.com/ar-io/ar-io-sdk/compare/v2.3.2...v2.4.0) (2024-11-12)
 
 

README.md

@@ -51,6 +51,7 @@ This is the home of [ar.io] SDK. This SDK provides functionality for interacting
     - [`updateGatewaySettings(gatewaySettings)`](#updategatewaysettingsgatewaysettings)
     - [`increaseDelegateStake({ target, qty })`](#increasedelegatestake-target-qty-)
     - [`decreaseDelegateStake({ target, qty, instant })`](#decreasedelegatestake-target-qty-instant-)
+    - [`getDelegations({ address, cursor, limit, sortBy, sortOrder })`](#getdelegations-address-cursor-limit-sortby-sortorder-)
     - [`instantWithdrawal({ gatewayAddress, vaultId })`](#instantwithdrawal-gatewayaddress-vaultid-)
     - [`increaseOperatorStake({ qty })`](#increaseoperatorstake-qty-)
     - [`decreaseOperatorStake({ qty })`](#decreaseoperatorstake-qty-)
@@ -1201,6 +1202,55 @@ const { id: txId } = await io.decreaseDelegateStake({
 });
 ```
 
+#### `getDelegations({ address, cursor, limit, sortBy, sortOrder })`
+
+Retrieves all active and vaulted stakes across all gateways for a specific address, paginated and sorted by the specified criteria. The `cursor` used for pagination is the last delegationId (concatenated gateway and startTimestamp of the delgation) from the previous request.
+
+```typescript
+const io = IO.init();
+const vaults = await io.getDelegations({
+  address: 't4Xr0_J4Iurt7caNST02cMotaz2FIbWQ4Kbj616RHl3',
+  cursor: 'QGWqtJdLLgm2ehFWiiPzMaoFLD50CnGuzZIPEdoDRGQ_123456789',
+  limit: 2,
+  sortBy: 'startTimestamp',
+  sortOrder: 'asc',
+});
+```
+
+<details>
+  <summary>Output</summary>
+
+```json
+{
+  "sortOrder": "asc",
+  "hasMore": true,
+  "totalItems": 95,
+  "limit": 2,
+  "sortBy": "startTimestamp",
+  "items": [
+    {
+      "type": "stake",
+      "startTimestamp": 1727815440632,
+      "gatewayAddress": "QGWqtJdLLgm2ehFWiiPzMaoFLD50CnGuzZIPEdoDRGQ",
+      "delegationId": "QGWqtJdLLgm2ehFWiiPzMaoFLD50CnGuzZIPEdoDRGQ_1727815440632",
+      "balance": 1383212512
+    },
+    {
+      "type": "vault",
+      "startTimestamp": 1730996691117,
+      "gatewayAddress": "QGWqtJdLLgm2ehFWiiPzMaoFLD50CnGuzZIPEdoDRGQ",
+      "delegationId": "QGWqtJdLLgm2ehFWiiPzMaoFLD50CnGuzZIPEdoDRGQ_1730996691117",
+      "vaultId": "_sGDS7X1hyLCVpfe40GWioH9BSOb7f0XWbhHBa1q4-g",
+      "balance": 50000000,
+      "endTimestamp": 1733588691117
+    }
+  ],
+  "nextCursor": "QGWqtJdLLgm2ehFWiiPzMaoFLD50CnGuzZIPEdoDRGQ_1730996691117"
+}
+```
+
+</details>
+
 #### `instantWithdrawal({ gatewayAddress, vaultId })`
 
 Instantly withdraws an existing vault on a gateway. If no `gatewayAddress` is provided, the signer's address will be used.
@@ -1549,36 +1599,43 @@ const records = await ant.getRecords();
   <summary>Output</summary>
 
 ```json
-{
-  "@": {
+[
+  {
+    "name": "@",
     "transactionId": "nOXJjj_vk0Dc1yCgdWD8kti_1iHruGzLQLNNBHVpN0Y",
     "ttlSeconds": 3600
   },
-  "cn": {
+  {
+    "name": "cn",
     "transactionId": "_HquerT6pfGFXrVxRxQTkJ7PV5RciZCqvMjLtUY0C1k",
     "ttlSeconds": 3300
   },
-  "dapp": {
+  {
+    "name": "dapp",
     "transactionId": "hxlxVgAG0K4o3fVD9T6Q4VBWpPmMZwMWgRh1kcuh3WU",
     "ttlSeconds": 3600
   },
-  "logo": {
+  {
+    "name": "logo",
     "transactionId": "KKmRbIfrc7wiLcG0zvY1etlO0NBx1926dSCksxCIN3A",
     "ttlSeconds": 3600
   },
-  "og": {
+  {
+    "name": "og",
     "transactionId": "YzD_Pm5VAfYpMD3zQCgMUcKKuleGhEH7axlrnrDCKBo",
     "ttlSeconds": 3600
   },
-  "og_dapp": {
+  {
+    "name": "og_dapp",
     "transactionId": "5iR4wBu4KUV1pUz1YpYE1ARXSRHUT5G2ptMuoN2JDlI",
     "ttlSeconds": 3600
   },
-  "og_logo": {
+  {
+    "name": "og_logo",
     "transactionId": "TB2wJyKrPnkAW79DAwlJYwpgdHKpijEJWQfcwX715Co",
     "ttlSeconds": 3600
   }
-}
+]
 ```
 
 </details>

examples/webpack/yarn.lock

@@ -4113,9 +4113,9 @@ http-parser-js@>=0.5.1:
   integrity sha512-SGeBX54F94Wgu5RH3X5jsDtf4eHyRogWX1XGT3b4HuW3tQPM4AaBzoUji/4AAJNXCEOWZ5O0DgZmJw1947gD5Q==
 
 http-proxy-middleware@^2.0.3:
-  version "2.0.6"
-  resolved "https://registry.yarnpkg.com/http-proxy-middleware/-/http-proxy-middleware-2.0.6.tgz#e1a4dd6979572c7ab5a4e4b55095d1f32a74963f"
-  integrity sha512-ya/UeJ6HVBYxrgYotAZo1KvPWlgB48kUJLDePFeneHsVujFaW5WNj2NgWCAE//B1Dl02BIfYlpNgBy8Kf8Rjmw==
+  version "2.0.7"
+  resolved "https://registry.yarnpkg.com/http-proxy-middleware/-/http-proxy-middleware-2.0.7.tgz#915f236d92ae98ef48278a95dedf17e991936ec6"
+  integrity sha512-fgVY8AV7qU7z/MmXJ/rxwbrtQH4jBQ9m7kp3llF0liB7glmFeVZFBepQb32T3y8n8k2+AEYuMPCpinYW+/CuRA==
   dependencies:
     "@types/http-proxy" "^1.17.8"
     http-proxy "^1.18.1"

package.json

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

src/common/ant.ts

@@ -18,14 +18,15 @@ import { z } from 'zod';
 import {
   AntBalancesSchema,
   AntControllersSchema,
+  AntEntriesSchema,
   AntInfoSchema,
   AntReadOptions,
   AntRecordSchema,
-  AntRecordsSchema,
   AntStateSchema,
   AoANTInfo,
   AoANTRead,
   AoANTRecord,
+  AoANTRecordEntry,
   AoANTState,
   AoANTWrite,
 } from '../types/ant.js';
@@ -40,7 +41,7 @@ import {
   isProcessConfiguration,
   isProcessIdConfiguration,
 } from '../types/index.js';
-import { createAoSigner } from '../utils/ao.js';
+import { createAoSigner, parseAntRecords } from '../utils/ao.js';
 import { parseSchemaResult } from '../utils/schema.js';
 import { AOProcess, InvalidContractConfigurationError } from './index.js';
 
@@ -154,7 +155,7 @@ export class AoANTReadable implements AoANTRead {
   }
 
   /**
-   * @returns {Promise<Record<string, AoANTRecord>>} All the undernames managed by the ANT.
+   * @returns {Promise<AoANTRecordEntry[]>} All the undernames managed by the ANT.
    * @example
    * Get the current records
    * ```ts
@@ -163,13 +164,19 @@ export class AoANTReadable implements AoANTRead {
    */
   async getRecords(
     { strict }: AntReadOptions = { strict: this.strict },
-  ): Promise<Record<string, AoANTRecord>> {
+  ): Promise<AoANTRecordEntry[]> {
     const tags = [{ name: 'Action', value: 'Records' }];
-    const records = await this.process.read<Record<string, AoANTRecord>>({
+    const records = await this.process.read<
+      AoANTRecordEntry[] | Record<string, AoANTRecord>
+    >({
       tags,
     });
-    if (strict) parseSchemaResult(AntRecordsSchema, records);
-    return records;
+
+    const result = parseAntRecords(records);
+
+    if (strict) parseSchemaResult(AntEntriesSchema, result);
+
+    return result;
   }
 
   /**

src/common/io.ts

@@ -42,6 +42,7 @@ import {
 import {
   AoArNSNameData,
   AoAuctionPriceData,
+  AoDelegation,
   AoEpochData,
   AoEpochSettings,
   AoGateway,
@@ -637,6 +638,22 @@ export class IOReadable implements AoIORead {
       tags: prunedPriceTags,
     });
   }
+
+  async getDelegations(
+    params: PaginationParams<AoDelegation> & { address: WalletAddress },
+  ): Promise<PaginationResult<AoDelegation>> {
+    const allTags = [
+      { name: 'Action', value: 'Paginated-Delegations' },
+      { name: 'Cursor', value: params.cursor?.toString() },
+      { name: 'Limit', value: params.limit?.toString() },
+      { name: 'Sort-By', value: params.sortBy },
+      { name: 'Sort-Order', value: params.sortOrder },
+      { name: 'Address', value: params.address },
+    ];
+    return this.process.read<PaginationResult<AoDelegation>>({
+      tags: pruneTags(allTags),
+    });
+  }
 }
 
 export class IOWriteable extends IOReadable implements AoIOWrite {

src/constants.ts

@@ -40,6 +40,6 @@ export const IO_TESTNET_PROCESS_ID =
 export const ANT_REGISTRY_ID = 'i_le_yKKPVstLTDSmkHRqf-wYphMnwB9OhleiTgMkWc';
 export const MIO_PER_IO = 1_000_000;
 export const AOS_MODULE_ID = 'cbn0KKrBZH7hdNkNokuXLtGryrWM--PjSTBqIzw9Kkk';
-export const ANT_LUA_ID = 'pOh2yupSaQCrLI_-ah8tVTiusUdVNTxxeWTQQHNdf30';
+export const ANT_LUA_ID = 'AWO2a2lVfQnjPFThjE4Uuw4ZFAd9EsCHBEgDYkJA-kk'; // v8 id test - remove comment when updated with actual v8 id.
 export const DEFAULT_SCHEDULER_ID =
   '_GQ33BkPtZrqxA84vM8Zk-N2aO0toNNu_C-l-rawrBA';

src/types/ant.ts

@@ -56,9 +56,15 @@ export const AntRecordSchema = z.object({
   transactionId: ArweaveTxIdSchema.describe('The Target ID of the undername'),
   ttlSeconds: z.number(),
 });
+export const AntEntrySchema = z.intersection(
+  AntRecordSchema,
+  z.object({ name: z.string() }),
+);
 export type AoANTRecord = z.infer<typeof AntRecordSchema>;
+export type AoANTRecordEntry = z.infer<typeof AntEntrySchema>;
 
 export const AntRecordsSchema = z.record(z.string(), AntRecordSchema);
+export const AntEntriesSchema = z.array(AntEntrySchema);
 export const AntControllersSchema = z.array(
   ArweaveTxIdSchema.describe('Controller address'),
 );
@@ -180,7 +186,7 @@ export interface AoANTRead {
     { undername }: { undername: string },
     opts?: AntReadOptions,
   ): Promise<AoANTRecord | undefined>;
-  getRecords(opts?: AntReadOptions): Promise<Record<string, AoANTRecord>>;
+  getRecords(opts?: AntReadOptions): Promise<AoANTRecordEntry[]>;
   getOwner(opts?: AntReadOptions): Promise<WalletAddress>;
   getControllers(): Promise<WalletAddress[]>;
   getTicker(opts?: AntReadOptions): Promise<string>;

src/types/io.ts

@@ -296,6 +296,26 @@ export type AoAuctionPriceData = {
   currentPrice: number;
 };
 
+export type AoDelegationBase = {
+  type: 'stake' | 'vault';
+  gatewayAddress: WalletAddress;
+  delegationId: string;
+};
+
+export type AoVaultDelegation = AoDelegationBase &
+  AoVaultData & {
+    type: 'vault';
+    vaultId: TransactionId;
+  };
+
+export type AoStakeDelegation = AoDelegationBase & {
+  type: 'stake';
+  startTimestamp: Timestamp;
+  balance: number;
+};
+
+export type AoDelegation = AoStakeDelegation | AoVaultDelegation;
+
 // Input types
 
 // TODO: confirm what is required or if all can be optional and defaults will be provided
@@ -342,6 +362,9 @@ export interface AoIORead {
   getGateways(
     params?: PaginationParams<AoGatewayWithAddress>,
   ): Promise<PaginationResult<AoGatewayWithAddress>>;
+  getDelegations(
+    params: PaginationParams<AoDelegation> & { address: WalletAddress },
+  ): Promise<PaginationResult<AoDelegation>>;
   getBalance(params: { address: WalletAddress }): Promise<number>;
   getBalances(
     params?: PaginationParams<AoBalanceWithAddress>,

src/utils/ao.ts

@@ -26,7 +26,7 @@ import {
   AOS_MODULE_ID,
   DEFAULT_SCHEDULER_ID,
 } from '../constants.js';
-import { AoANTRecord } from '../types/ant.js';
+import { AoANTRecord, AoANTRecordEntry } from '../types/ant.js';
 import {
   AoClient,
   AoSigner,
@@ -253,3 +253,30 @@ export function createAoSigner(signer: ContractSigner): AoSigner {
 
   return aoSigner;
 }
+
+/**
+ * @param records @type {AoANTRecordEntry[] | Record<string, AoANTRecord>} - the records returned by an ANT
+ * @returns @type {AoANTRecordEntry[]} - the alphabetically sorted records
+ */
+export function parseAntRecords(
+  records: AoANTRecordEntry[] | Record<string, AoANTRecord>,
+): AoANTRecordEntry[] {
+  const result = Array.isArray(records)
+    ? records // assumes if records is an array that its AoANTRecordEntry[]
+    : // backwards compatibility for when ANTs returned as Record<string, AoANTRecord>
+      Object.keys(records) // sort the keys since string indexed maps in lua do not retain order
+        .sort((a: string, b: string) => {
+          if (a == '@') return -1;
+          if (b == '@') return 1;
+          return a.localeCompare(b);
+        })
+        .reduce((acc: AoANTRecordEntry[], undername: string) => {
+          acc.push({
+            ...records[undername],
+            name: undername,
+          });
+          return acc;
+        }, [] as AoANTRecordEntry[]);
+
+  return result;
+}

src/version.ts

@@ -16,4 +16,4 @@
 
 // AUTOMATICALLY GENERATED FILE - DO NOT TOUCH
 
-export const version = '2.4.0';
+export const version = '2.5.0-alpha.3';