@ar.io/sdk 2.0.0-alpha.10 → 2.0.0-alpha.11

package/README.md

@@ -25,7 +25,7 @@ This is the home of [ar.io] SDK. This SDK provides functionality for interacting
     - [`getGateway({ address })`](#getgateway-address-)
     - [`getGateways({ cursor, limit, sortBy, sortOrder })`](#getgateways-cursor-limit-sortby-sortorder-)
     - [`getArNSRecord({ name })`](#getarnsrecord-name-)
-    - [`getArNSRecords({ page, pageSize, sortBy, sortOrder })`](#getarnsrecords-cursor-limit-sortby-sortorder-)
+    - [`getArNSRecords({ cursor, limit, sortBy, sortOrder })`](#getarnsrecords-cursor-limit-sortby-sortorder-)
     - [`getObservations({ epochIndex })`](#getobservations-epochindex-)
     - [`getDistributions({ epochIndex })`](#getdistributions-epochindex-)
     - [`getEpoch({ epochIndex })`](#getepoch-epochindex-)
@@ -47,7 +47,7 @@ This is the home of [ar.io] SDK. This SDK provides functionality for interacting
 - [Arweave Name Tokens (ANT's)](#arweave-name-tokens-ants)
 
   - [ANT APIs](#ant-apis)
-    - [`init({ signer})`](#init-signer-)
+    - [`init({ processId, signer })`](#init-processid-signer-)
     - [`getInfo()`](#getinfo)
     - [`getOwner()`](#getowner)
     - [`getControllers()`](#getcontrollers)
@@ -65,6 +65,8 @@ This is the home of [ar.io] SDK. This SDK provides functionality for interacting
 
   - [Configuration](#configuration)
 
+- [Pagination](#pagination)
+
 - [Developers](#developers)
   - [Requirements](#requirements)
   - [Setup \& Build](#setup--build)
@@ -103,37 +105,36 @@ const gateways = await io.getGateways();
 
 ```json
 {
-  "QGWqtJdLLgm2ehFWiiPzMaoFLD50CnGuzZIPEdoDRGQ": {
-    "end": 0,
-    "observerWallet": "IPdwa3Mb_9pDD8c2IaJx6aad51Ss-_TfStVwBuhtXMs",
-    "operatorStake": 250000000000, // value in mIO
-    "settings": {
-      "fqdn": "ar-io.dev",
-      "label": "AR.IO Test",
-      "note": "Test Gateway operated by PDS for the AR.IO ecosystem.",
-      "port": 443,
-      "properties": "raJgvbFU-YAnku-WsupIdbTsqqGLQiYpGzoqk9SCVgY",
-      "protocol": "https"
-    },
-    "start": 1256694,
-    "stats": {
-      "failedConsecutiveEpochs": 0,
-      "passedEpochCount": 30,
-      "submittedEpochCount": 30,
-      "totalEpochParticipationCount": 31,
-      "totalEpochsPrescribedCount": 31
-    },
-    "status": "joined",
-    "vaults": {},
-    "weights": {
-      "stakeWeight": 25,
-      "tenureWeight": 0.9031327160493827,
-      "gatewayRewardRatioWeight": 0.96875,
-      "observerRewardRatioWeight": 0.96875,
-      "compositeWeight": 21.189222170982834,
-      "normalizedCompositeWeight": 0.27485583057217183
+  "items": [
+    {
+      "gatewayAddress": "QGWqtJdLLgm2ehFWiiPzMaoFLD50CnGuzZIPEdoDRGQ",
+      "observerAddress": "IPdwa3Mb_9pDD8c2IaJx6aad51Ss-_TfStVwBuhtXMs",
+      "operatorStake": 250000000000,
+      "settings": {
+        "fqdn": "ar-io.dev",
+        "label": "AR.IO Test",
+        "note": "Test Gateway operated by PDS for the AR.IO ecosystem.",
+        "port": 443,
+        "properties": "raJgvbFU-YAnku-WsupIdbTsqqGLQiYpGzoqk9SCVgY",
+        "protocol": "https"
+      },
+      "startTimestamp": 1720720621424,
+      "stats": {
+        "failedConsecutiveEpochs": 0,
+        "passedEpochCount": 30,
+        "submittedEpochCount": 30,
+        "totalEpochParticipationCount": 31,
+        "totalEpochsPrescribedCount": 31
+      },
+      "status": "joined",
+      "vaults": {}
     }
-  }
+  ],
+  "hasMore": true,
+  "nextCursor": "-4xgjroXENKYhTWqrBo57HQwvDL51mMdfsdsxJy6Y2Z_sA",
+  "totalItems": 316,
+  "sortBy": "startTimestamp",
+  "sortOrder": "desc"
 }
 ```
 
@@ -216,11 +217,9 @@ import { IOToken, mIOToken } from '@ar.io/sdk';
 
 const ioValue = 1;
 const mIOValue = new IOToken(ioValue).toMIO();
-console.log(mIOValue); // 1000000 (mIO)
 
 const mIOValue = 1_000_000;
 const ioValue = new mIOToken(mIOValue).toIO();
-console.log(ioValue); // 1 (IO)
 ```
 
 ## IO Process
@@ -275,7 +274,7 @@ const io = IO.init();
 // the balance will be returned in mIO as a value
 const balance = await io
   .getBalance({
-    address: 'INSERT_WALLET_ADDRESS',
+    address: 'QGWqtJdLLgm2ehFWiiPzMaoFLD50CnGuzZIPEdoDRGQ',
   })
   .then((balance) => new mIOToken().toIO()); // convert it to IO for readability
 ```
@@ -291,7 +290,7 @@ const balance = await io
 
 #### `getBalances({ cursor, limit, sortBy, sortOrder })`
 
-Retrieves the balances of the IO process in `mIO`, paginated and sorted by the specified criteria. The `cursor` used for pagination is the last wallet address from the previous page.
+Retrieves the balances of the IO process in `mIO`, paginated and sorted by the specified criteria. The `cursor` used for pagination is the last wallet address from the previous request.
 
 ```typescript
 const io = IO.init();
@@ -307,20 +306,19 @@ const balances = await io.getBalances({
   <summary>Output</summary>
 
 ```json
-[
-  {
-    "address": "-4xgjroXENKYhTWqrBo57HQwvDL51mMvSxJy6Y2Z_sA",
-    "balance": 1000000
-  },
-  {
-    "address": "-7vXsQZQDk8TMDlpiSLy3CnLi5PDPlAaN2DaynORpck",
-    "balance": 500000
-  },
-  {
-    "address": "IPdwa3Mb_9pDD8c2IaJx6aad51Ss-_TfStVwBuhtXMs",
-    "balance": 10000
-  }
-]
+{
+  "items": [
+    {
+      "address": "-4xgjroXENKYhTWqrBo57HQwvDL51mMvSxJy6Y2Z_sA",
+      "balance": 1000000
+    }
+  ],
+  "hasMore": true,
+  "nextCursor": "-7vXsQZQDk8TMDlpiSLy3CnLi5PDPlAaN2DaynORpck",
+  "totalItems": 1789,
+  "sortBy": "balance",
+  "sortOrder": "desc"
+}
 ```
 
 </details>
@@ -332,7 +330,7 @@ Retrieves a gateway's info by its staking wallet address.
 ```typescript
 const io = IO.init();
 const gateway = await io.getGateway({
-  address: 'INSERT_GATEWAY_ADDRESS',
+  address: '-7vXsQZQDk8TMDlpiSLy3CnLi5PDPlAaN2DaynORpck',
 });
 ```
 
@@ -341,8 +339,7 @@ const gateway = await io.getGateway({
 
 ```json
 {
-  "end": 0,
-  "observerWallet": "IPdwa3Mb_9pDD8c2IaJx6aad51Ss-_TfStVwBuhtXMs",
+  "observerAddress": "IPdwa3Mb_9pDD8c2IaJx6aad51Ss-_TfStVwBuhtXMs",
   "operatorStake": 250000000000,
   "settings": {
     "fqdn": "ar-io.dev",
@@ -352,7 +349,7 @@ const gateway = await io.getGateway({
     "properties": "raJgvbFU-YAnku-WsupIdbTsqqGLQiYpGzoqk9SCVgY",
     "protocol": "https"
   },
-  "start": 1256694,
+  "startTimestamp": 1720720620813,
   "stats": {
     "failedConsecutiveEpochs": 0,
     "passedEpochCount": 30,
@@ -369,12 +366,12 @@ const gateway = await io.getGateway({
 
 #### `getGateways({ cursor, limit, sortBy, sortOrder })`
 
-Retrieves registered gateways of the IO process, using pagination and sorting by the specified criteria. The `cursor` used for pagination is the last gateway address from the previous page.
+Retrieves registered gateways of the IO process, using pagination and sorting by the specified criteria. The `cursor` used for pagination is the last gateway address from the previous request.
 
 ```typescript
 const io = IO.init();
 const gateways = await io.getGateways({
-  limit: 10,
+  limit: 1,
   sortOrder: 'desc',
   sortBy: 'operatorStake',
 });
@@ -386,54 +383,38 @@ Available `sortBy` options are any of the keys on the gateway object, e.g. `oper
   <summary>Output</summary>
 
 ```json
-[
-  {
-    "gatewayAddress": "QGWqtJdLLgm2ehFWiiPzMaoFLD50CnGuzZIPEdoDRGQ",
-    "observerAddress": "IPdwa3Mb_9pDD8c2IaJx6aad51Ss-_TfStVwBuhtXMs",
-    "operatorStake": 250000000000,
-    "settings": {
-      "fqdn": "ar-io.dev",
-      "label": "AR.IO Test",
-      "note": "Test Gateway operated by PDS for the AR.IO ecosystem.",
-      "port": 443,
-      "properties": "raJgvbFU-YAnku-WsupIdbTsqqGLQiYpGzoqk9SCVgY",
-      "protocol": "https"
-    },
-    "start": 1256694,
-    "stats": {
-      "failedConsecutiveEpochs": 0,
-      "passedEpochCount": 30,
-      "submittedEpochCount": 30,
-      "totalEpochParticipationCount": 31,
-      "totalEpochsPrescribedCount": 31
-    },
-    "status": "joined",
-    "vaults": {}
-  },
-  {
-    "gatewayAddress": "bh9l1cy0aksiL_x9M359faGzM_yjralacHIUo8_nQXM",
-    "observerAddress": "bh9l1cy0aksiL_x9M359faGzM_yjralacHIUo8_nQXM",
-    "operatorStake": 100000000,
-    "settings": {
-      "fqdn": "ar-io.dev",
-      "label": "AR.IO Test",
-      "note": "Test Gateway operated by PDS for the AR.IO ecosystem.",
-      "port": 443,
-      "properties": "raJgvbFU-YAnku-WsupIdbTsqqGLQiYpGzoqk9SCVgY",
-      "protocol": "https"
-    },
-    "start": 1256694,
-    "stats": {
-      "failedConsecutiveEpochs": 0,
-      "passedEpochCount": 30,
-      "submittedEpochCount": 30,
-      "totalEpochParticipationCount": 31,
-      "totalEpochsPrescribedCount": 31
-    },
-    "status": "joined",
-    "vaults": {}
-  }
-]
+{
+  "items": [
+    {
+      "gatewayAddress": "QGWqtJdLLgm2ehFWiiPzMaoFLD50CnGuzZIPEdoDRGQ",
+      "observerAddress": "IPdwa3Mb_9pDD8c2IaJx6aad51Ss-_TfStVwBuhtXMs",
+      "operatorStake": 250000000000,
+      "settings": {
+        "fqdn": "ar-io.dev",
+        "label": "AR.IO Test",
+        "note": "Test Gateway operated by PDS for the AR.IO ecosystem.",
+        "port": 443,
+        "properties": "raJgvbFU-YAnku-WsupIdbTsqqGLQiYpGzoqk9SCVgY",
+        "protocol": "https"
+      },
+      "startTimestamp": 1720720620813,
+      "stats": {
+        "failedConsecutiveEpochs": 0,
+        "passedEpochCount": 30,
+        "submittedEpochCount": 30,
+        "totalEpochParticipationCount": 31,
+        "totalEpochsPrescribedCount": 31
+      },
+      "status": "joined",
+      "vaults": {}
+    }
+  ],
+  "hasMore": true,
+  "nextCursor": "-4xgjroXENKYhTWqrBo57HQwvDL51mMdfsdsxJy6Y2Z_sA",
+  "totalItems": 316,
+  "sortBy": "operatorStake",
+  "sortOrder": "desc"
+}
 ```
 
 </details>
@@ -453,8 +434,8 @@ const record = await io.getArNSRecord({ name: 'ardrive' });
 ```json
 {
   "processId": "bh9l1cy0aksiL_x9M359faGzM_yjralacHIUo8_nQXM",
-  "endTimestamp": 1711122739,
-  "startTimestamp": 1694101828,
+  "endTimestamp": 1752256702026,
+  "startTimestamp": 1720720819969,
   "type": "lease",
   "undernames": 100
 }
@@ -464,13 +445,13 @@ const record = await io.getArNSRecord({ name: 'ardrive' });
 
 #### `getArNSRecords({ cursor, limit, sortBy, sortOrder })`
 
-Retrieves all registered ArNS records of the IO process, paginated and sorted by the specified criteria. The `cursor` used for pagination is the last ArNS name from the previous page.
+Retrieves all registered ArNS records of the IO process, paginated and sorted by the specified criteria. The `cursor` used for pagination is the last ArNS name from the previous request.
 
 ```typescript
 const io = IO.init();
+// get the 5 newest names
 const records = await io.getArNSRecords({
-  cursor: 'ar-io',
-  pageSize: 10,
+  limit: 5,
   sortBy: 'startTimestamp',
   sortOrder: 'desc',
 });
@@ -482,24 +463,55 @@ Available `sortBy` options are any of the keys on the record object, e.g. `name`
   <summary>Output</summary>
 
 ```json
-[
-  {
-    "name": "ao",
-    "processId": "eNey-H9RB9uCdoJUvPULb35qhZVXZcEXv8xds4aHhkQ",
-    "purchasePrice": 75541282285,
-    "startTimestamp": 1706747215,
-    "type": "permabuy",
-    "undernames": 10
-  },
-  {
-    "name": "ardrive",
-    "processId": "bh9l1cy0aksiL_x9M359faGzM_yjralacHIUo8_nQXM",
-    "endTimestamp": 1711122739,
-    "startTimestamp": 1694101828,
-    "type": "lease",
-    "undernames": 100
-  }
-]
+{
+  "items": [
+    {
+      "name": "ao",
+      "processId": "eNey-H9RB9uCdoJUvPULb35qhZVXZcEXv8xds4aHhkQ",
+      "purchasePrice": 75541282285,
+      "startTimestamp": 1720720621424,
+      "type": "permabuy",
+      "undernames": 10
+    },
+    {
+      "name": "ardrive",
+      "processId": "bh9l1cy0aksiL_x9M359faGzM_yjralacHIUo8_nQXM",
+      "endTimestamp": 1720720819969,
+      "startTimestamp": 1720720620813,
+      "type": "lease",
+      "undernames": 100
+    },
+    {
+      "name": "arweave",
+      "processId": "bh9l1cy0aksiL_x9M359faGzM_yjralacHIUo8_nQXM",
+      "endTimestamp": 1720720819969,
+      "startTimestamp": 1720720620800,
+      "type": "lease",
+      "undernames": 100
+    },
+    {
+      "name": "ar-io",
+      "processId": "bh9l1cy0aksiL_x9M359faGzM_yjralacHIUo8_nQXM",
+      "endTimestamp": 1720720819969,
+      "startTimestamp": 1720720619000,
+      "type": "lease",
+      "undernames": 100
+    },
+    {
+      "name": "fwd",
+      "processId": "bh9l1cy0aksiL_x9M359faGzM_yjralacHIUo8_nQXM",
+      "endTimestamp": 1720720819969,
+      "startTimestamp": 1720720220811,
+      "type": "lease",
+      "undernames": 100
+    }
+  ],
+  "hasMore": true,
+  "nextCursor": "fwdresearch",
+  "totalItems": 21740,
+  "sortBy": "startTimestamp",
+  "sortOrder": "desc"
+}
 ```
 
 </details>
@@ -553,7 +565,7 @@ const distributions = await io.getDistributions();
 {
   "totalEligibleRewards": 100000000,
   "totalDistributedRewards": 100000000,
-  "distributedTimestamp": 1711122739,
+  "distributedTimestamp": 1720720621424,
   "rewards": {
     "IPdwa3Mb_9pDD8c2IaJx6aad51Ss-_TfStVwBuhtXMs": 100000000
   }
@@ -577,10 +589,10 @@ const epoch = await io.getEpoch({ epochIndex: 0 });
 ```json
 {
   "epochIndex": 0,
-  "startTimestamp": 1694101828,
-  "endTimestamp": 1711122739,
+  "startTimestamp": 1720720620813,
+  "endTimestamp": 1752256702026,
   "startHeight": 1350700,
-  "distributionTimestamp": 1711122739,
+  "distributionTimestamp": 1752256702026,
   "observations": {
     "failureSummaries": {
       "-Tk2DDk8k4zkwtppp_XFKKI5oUgh6IEHygAoN7mD-w8": [
@@ -597,7 +609,7 @@ const epoch = await io.getEpoch({ epochIndex: 0 });
       "gatewayAddress": "2Fk8lCmDegPg6jjprl57-UCpKmNgYiKwyhkU4vMNDnE",
       "observerAddress": "2Fk8lCmDegPg6jjprl57-UCpKmNgYiKwyhkU4vMNDnE",
       "stake": 10000000000, // value in mIO
-      "start": 1292450,
+      "startTimestamp": 1720720620813,
       "stakeWeight": 1,
       "tenureWeight": 0.4494598765432099,
       "gatewayRewardRatioWeight": 1,
@@ -607,7 +619,7 @@ const epoch = await io.getEpoch({ epochIndex: 0 });
     }
   ],
   "distributions": {
-    "distributedTimestamp": 1711122739,
+    "distributedTimestamp": 1752256702026,
     "totalEligibleRewards": 100000000,
     "totoalDistributedRewards": 100000000,
     "rewards": {
@@ -634,8 +646,8 @@ const epoch = await io.getCurrentEpoch();
 ```json
 {
   "epochIndex": 0,
-  "startTimestamp": 1694101828,
-  "endTimestamp": 1711122739,
+  "startTimestamp": 1720720621424,
+  "endTimestamp": 1752256702026,
   "startHeight": 1350700,
   "distributionTimestamp": 1711122739,
   "observations": {
@@ -894,7 +906,6 @@ const { id: txId } = await io.transfer(
   {
     target: '-5dV7nk7waR8v4STuwPnTck1zFVkQqJh5K9q9Zik4Y5',
     qty: new IOToken(1000).toMIO(),
-    denomination: 'IO',
   },
   // optional additional tags
   { tags: [{ name: 'App-Name', value: 'My-Awesome-App' }] },
@@ -960,7 +971,7 @@ The ANT client class exposes APIs relevant to compliant Arweave Name Token proce
 
 ### ANT APIs
 
-#### `init({ signer )`
+#### `init({ processId, signer )`
 
 Factory function to that creates a read-only or writeable client. By providing a `signer` additional write APIs that require signing, like `setRecord` and `transfer` are available. By default, a read-only client is returned and no write APIs are available.
 
@@ -1219,6 +1230,33 @@ Logger.default.setLogLevel('debug');
 Logger.default = winston.createLogger({ ...loggerConfigs }); // or some other logger that satisifes ILogger interface
 ```
 
+## Pagination
+
+Certain APIs that could return a large amount of data are paginated using cursors. The SDK uses the `cursor` pattern (as opposed to pages) to better protect against changing data while paginating through a list of items. For more information on pagination strategies refer to [this article](https://www.getknit.dev/blog/api-pagination-best-practices#api-pagination-techniques-).
+
+Paginated results include the following properties:
+
+- `items`: the list of items on the current request, defaulted to 100 items.
+- `nextCursor`: the cursor to use for the next batch of items. This is `undefined` if there are no more items to fetch.
+- `hasMore`: a boolean indicating if there are more items to fetch. This is `false` if there are no more items to fetch.
+- `totalItems`: the total number of items available. This may change as new items are added to the list, only use this for informational purposes.
+- `sortBy`: the field used to sort the items, by default this is `startTimestamp`.
+- `sortOrder`: the order used to sort the items, by default this is `desc`.
+
+To request all the items in a list, you can iterate through the list using the `nextCursor` until `hasMore` is `false`.
+
+```typescript
+let hasMore = true;
+let cursor: string | undefined;
+const gateaways = [];
+while (hasMore) {
+  const page = await io.getGateways({ limit: 10, cursor });
+  gateaways.push(...items);
+  cursor = page.nextCursor;
+  hasMore = page.hasMore;
+}
+```
+
 ## Developers
 
 ### Requirements
@@ -1235,7 +1273,9 @@ Logger.default = winston.createLogger({ ...loggerConfigs }); // or some other lo
 
 ### Testing
 
-- `yarn test:integration` - runs integration tests against a local AO testnet
+- `yarn test` - runs e2e tests and unit tests
+- `yarn test:e2e` - runs e2e tests
+- `yarn test:unit` - runs unit tests
 - `yarn example:web` - opens up the example web page
 - `yarn example:cjs` - runs example CJS node script
 - `yarn example:esm` - runs example ESM node script