@ar.io/sdk 2.5.3-alpha.2 → 2.5.3-alpha.4

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -23,52 +23,57 @@ This is the home of [ar.io] SDK. This SDK provides functionality for interacting
23
23
  - [IOToken & mIOToken](#iotoken--miotoken)
24
24
  - [Converting IO to mIO](#converting-io-to-mio)
25
25
  - [IO Process](#io-process)
26
- - [APIs](#apis)
26
+ - [General](#general)
27
27
  - [`init({ signer })`](#init-signer-)
28
28
  - [`getInfo()`](#getinfo)
29
29
  - [`getTokenSupply()`](#gettokensupply)
30
30
  - [`getBalance({ address })`](#getbalance-address-)
31
31
  - [`getBalances({ cursor, limit, sortBy, sortOrder })`](#getbalances-cursor-limit-sortby-sortorder-)
32
+ - [`transfer({ target, qty })`](#transfer-target-qty-)
33
+ - [Vaults](#vaults)
32
34
  - [`getVault({ address, vaultId })`](#getvault-address-vaultid-)
33
35
  - [`getVaults({ cursor, limit, sortBy, sortOrder })`](#getvaults-cursor-limit-sortby-sortorder-)
36
+ - [Gateways](#gateways)
34
37
  - [`getGateway({ address })`](#getgateway-address-)
35
38
  - [`getGateways({ cursor, limit, sortBy, sortOrder })`](#getgateways-cursor-limit-sortby-sortorder-)
36
- - [`buyRecord({ name, type, years, processId })`](#buyrecord-name-type-years-processid-)
37
- - [`getArNSRecord({ name })`](#getarnsrecord-name-)
38
- - [`getArNSRecords({ cursor, limit, sortBy, sortOrder })`](#getarnsrecords-cursor-limit-sortby-sortorder-)
39
- - [`getArNSAuctions({ cursor, limit, sortBy, sortOrder })`](#getarnsauctions-cursor-limit-sortby-sortorder-)
40
- - [`getArNSAuction({ name })`](#getarnsauction-name-)
41
- - [`getArNSAuctionPrices({ name, type, years, intervalMs })`](#getarnsauctionprices-name-type-years-intervalms-)
42
- - [`getDemandFactor()`](#getdemandfactor)
43
- - [`getObservations({ epochIndex })`](#getobservations-epochindex-)
44
- - [`getDistributions({ epochIndex })`](#getdistributions-epochindex-)
45
- - [`getEpoch({ epochIndex })`](#getepoch-epochindex-)
46
- - [`getCurrentEpoch()`](#getcurrentepoch)
47
- - [`getPrescribedObservers({ epochIndex })`](#getprescribedobservers-epochindex-)
48
- - [`getTokenCost({ intent, ...args })`](#gettokencost-intent-args-)
49
39
  - [`joinNetwork(params)`](#joinnetworkparams)
50
40
  - [`leaveNetwork()`](#leavenetwork)
51
- - [`updateGatewaySettings(gatewaySettings)`](#updategatewaysettingsgatewaysettings)
41
+ - [`updateGatewaySettings({ ...settings })`](#updategatewaysettings-settings-)
52
42
  - [`increaseDelegateStake({ target, qty })`](#increasedelegatestake-target-qty-)
53
43
  - [`decreaseDelegateStake({ target, qty, instant })`](#decreasedelegatestake-target-qty-instant-)
54
44
  - [`getDelegations({ address, cursor, limit, sortBy, sortOrder })`](#getdelegations-address-cursor-limit-sortby-sortorder-)
45
+ - [`instantWithdrawal({ gatewayAddress, vaultId })`](#instantwithdrawal-gatewayaddress-vaultid-)
46
+ - [`cancelWithdrawal({ gatewayAddress, vaultId })`](#cancelwithdrawal-gatewayaddress-vaultid-)
55
47
  - [`getAllowedDelegates({ address, cursor, limit, sortBy, sortOrder })`](#getalloweddelegates-address-cursor-limit-sortby-sortorder-)
56
48
  - [`getGatewayVaults({ address, cursor, limit, sortBy, sortOrder })`](#getgatewayvaults-address-cursor-limit-sortby-sortorder-)
57
- - [`instantWithdrawal({ gatewayAddress, vaultId })`](#instantwithdrawal-gatewayaddress-vaultid-)
58
49
  - [`increaseOperatorStake({ qty })`](#increaseoperatorstake-qty-)
59
50
  - [`decreaseOperatorStake({ qty })`](#decreaseoperatorstake-qty-)
60
- - [`saveObservations({ reportTxId, failedGateways })`](#saveobservations-reporttxid-failedgateways-)
61
- - [`transfer({ target, qty })`](#transfer-target-qty-)
51
+ - [`redelegateStake({ target, source, stakeQty, vaultId })`](#redelegatestake-target-source-stakeqty-vaultid-)
52
+ - [`getRedelegationFee({ address })`](#getredelegationfee-address-)
53
+ - [Arweave Name System (ArNS)](#arweave-name-system-arns)
54
+ - [`buyRecord({ name, type, years, processId })`](#buyrecord-name-type-years-processid-)
55
+ - [`getArNSRecord({ name })`](#getarnsrecord-name-)
56
+ - [`getArNSRecords({ cursor, limit, sortBy, sortOrder })`](#getarnsrecords-cursor-limit-sortby-sortorder-)
62
57
  - [`increaseUndernameLimit({ name, qty })`](#increaseundernamelimit-name-qty-)
63
58
  - [`extendLease({ name, years })`](#extendlease-name-years-)
64
- - [`cancelWithdrawal({ gatewayAddress, vaultId })`](#cancelwithdrawal-gatewayaddress-vaultid-)
59
+ - [`getTokenCost({ intent, ...args })`](#gettokencost-intent-args-)
60
+ - [`getDemandFactor()`](#getdemandfactor)
61
+ - [`getArNSAuctions({ cursor, limit, sortBy, sortOrder })`](#getarnsauctions-cursor-limit-sortby-sortorder-)
62
+ - [`getArNSAuction({ name })`](#getarnsauction-name-)
63
+ - [`getArNSAuctionPrices({ name, type, years, intervalMs })`](#getarnsauctionprices-name-type-years-intervalms-)
65
64
  - [`submitAuctionBid({ name, type, years, processId })`](#submitauctionbid-name-type-years-processid-)
65
+ - [Epochs](#epochs)
66
+ - [`getCurrentEpoch()`](#getcurrentepoch)
67
+ - [`getEpoch({ epochIndex })`](#getepoch-epochindex-)
68
+ - [`getObservations({ epochIndex })`](#getobservations-epochindex-)
69
+ - [`getDistributions({ epochIndex })`](#getdistributions-epochindex-)
70
+ - [`saveObservations({ reportTxId, failedGateways })`](#saveobservations-reporttxid-failedgateways-)
71
+ - [`getPrescribedObservers({ epochIndex })`](#getprescribedobservers-epochindex-)
72
+ - [Primary Names](#primary-names)
66
73
  - [`getPrimaryNames({ cursor, limit, sortBy, sortOrder })`](#getprimarynames-cursor-limit-sortby-sortorder-)
67
74
  - [`getPrimaryName({ name, address })`](#getprimaryname-name-address-)
68
75
  - [`requestPrimaryName({ name, address })`](#requestprimaryname-name-address-)
69
76
  - [`getPrimaryNameRequest({ initiator })`](#getprimarynamerequest-initiator-)
70
- - [`redelegateStake({ target, source, stakeQty, vaultId })`](#redelegatestake-target-source-stakeqty-vaultid-)
71
- - [`getRedelegationFee({ address })`](#getredelegationfee-address-)
72
77
  - [Configuration](#configuration)
73
78
  - [Arweave Name Tokens (ANT's)](#arweave-name-tokens-ants)
74
79
  - [ANT APIs](#ant-apis)
@@ -99,7 +104,7 @@ This is the home of [ar.io] SDK. This SDK provides functionality for interacting
99
104
  - [Pagination](#pagination)
100
105
  - [Resources](#resources)
101
106
  - [Bundling](#bundling)
102
- - [Gateways](#gateways)
107
+ - [Gateways](#gateways-1)
103
108
  - [Running a Gateway](#running-a-gateway)
104
109
  - [AO](#ao)
105
110
  - [Developers](#developers)
@@ -272,7 +277,7 @@ const ioValue = new mIOToken(mIOValue).toIO();
272
277
 
273
278
  ## IO Process
274
279
 
275
- ### APIs
280
+ ### General
276
281
 
277
282
  #### `init({ signer })`
278
283
 
@@ -411,7 +416,27 @@ const balances = await io.getBalances({
411
416
  ```
412
417
 
413
418
  </details>
414
-
419
+
420
+ #### `transfer({ target, qty })`
421
+
422
+ Transfers `mIO` to the designated `target` recipient address. Requires `signer` to be provided on `IO.init` to sign the transaction.
423
+
424
+ _Note: Requires `signer` to be provided on `IO.init` to sign the transaction._
425
+
426
+ ```typescript
427
+ const io = IO.init({ signer: new ArweaveSigner(jwk) });
428
+ const { id: txId } = await io.transfer(
429
+ {
430
+ target: '-5dV7nk7waR8v4STuwPnTck1zFVkQqJh5K9q9Zik4Y5',
431
+ qty: new IOToken(1000).toMIO(),
432
+ },
433
+ // optional additional tags
434
+ { tags: [{ name: 'App-Name', value: 'My-Awesome-App' }] },
435
+ );
436
+ ```
437
+
438
+ ### Vaults
439
+
415
440
  #### `getVault({ address, vaultId })`
416
441
 
417
442
  Retrieves the locked-balance user vault of the IO process by the specified wallet address and vault ID.
@@ -483,6 +508,8 @@ const vaults = await io.getVaults({
483
508
 
484
509
  </details>
485
510
 
511
+ ### Gateways
512
+
486
513
  #### `getGateway({ address })`
487
514
 
488
515
  Retrieves a gateway's info by its staking wallet address.
@@ -595,171 +622,230 @@ Available `sortBy` options are any of the keys on the gateway object, e.g. `oper
595
622
 
596
623
  </details>
597
624
 
598
- #### `buyRecord({ name, type, years, processId })`
625
+ #### `joinNetwork(params)`
599
626
 
600
- Purchases a new ArNS record with the specified name, type, and duration.
627
+ Joins a gateway to the ar.io network via its associated wallet.
601
628
 
602
629
  _Note: Requires `signer` to be provided on `IO.init` to sign the transaction._
603
630
 
604
631
  ```typescript
605
- const io = IO.init({ processId: IO_DEVNET_PROCESS_ID, signer });
606
- const record = await io.buyRecord(
607
- { name: 'ardrive', type: 'lease', years: 1 },
632
+ const io = IO.init({ signer: new ArweaveSigner(jwk) });
633
+ const { id: txId } = await io.joinNetwork(
608
634
  {
609
- // optional tags
610
- tags: [{ name: 'App-Name', value: 'ArNS-App' }],
635
+ qty: new IOToken(10_000).toMIO(), // minimum operator stake allowed
636
+ autoStake: true, // auto-stake operator rewards to the gateway
637
+ allowDelegatedStaking: true, // allows delegated staking
638
+ minDelegatedStake: new IOToken(100).toMIO(), // minimum delegated stake allowed
639
+ delegateRewardShareRatio: 10, // percentage of rewards to share with delegates (e.g. 10%)
640
+ label: 'john smith', // min 1, max 64 characters
641
+ note: 'The example gateway', // max 256 characters
642
+ properties: 'FH1aVetOoulPGqgYukj0VE0wIhDy90WiQoV3U2PeY44', // Arweave transaction ID containing additional properties of the Gateway
643
+ observerWallet: '0VE0wIhDy90WiQoV3U2PeY44FH1aVetOoulPGqgYukj', // wallet address of the observer, must match OBSERVER_WALLET on the observer
644
+ fqdn: 'example.com', // fully qualified domain name - note: you must own the domain and set the OBSERVER_WALLET on your gateway to match `observerWallet`
645
+ port: 443, // port number
646
+ protocol: 'https', // only 'https' is supported
611
647
  },
648
+ // optional additional tags
649
+ { tags: [{ name: 'App-Name', value: 'My-Awesome-App' }] },
612
650
  );
613
651
  ```
614
652
 
615
- #### `getArNSRecord({ name })`
653
+ #### `leaveNetwork()`
616
654
 
617
- Retrieves the record info of the specified ArNS name.
655
+ Sets the gateway as `leaving` on the ar.io network. Requires `signer` to be provided on `IO.init` to sign the transaction. The gateways operator and delegate stakes are vaulted and will be returned after leave periods. The gateway will be removed from the network after the leave period.
656
+
657
+ _Note: Requires `signer` to be provided on `IO.init` to sign the transaction._
618
658
 
619
659
  ```typescript
620
- const io = IO.init();
621
- const record = await io.getArNSRecord({ name: 'ardrive' });
660
+ const io = IO.init({ signer: new ArweaveSigner(jwk) });
661
+
662
+ const { id: txId } = await io.leaveNetwork(
663
+ // optional additional tags
664
+ { tags: [{ name: 'App-Name', value: 'My-Awesome-App' }] },
665
+ );
622
666
  ```
623
667
 
624
- <details>
625
- <summary>Output</summary>
668
+ #### `updateGatewaySettings({ ...settings })`
626
669
 
627
- ```json
628
- {
629
- "processId": "bh9l1cy0aksiL_x9M359faGzM_yjralacHIUo8_nQXM",
630
- "endTimestamp": 1752256702026,
631
- "startTimestamp": 1720720819969,
632
- "type": "lease",
633
- "undernames": 100
634
- }
670
+ Writes new gateway settings to the callers gateway configuration.
671
+
672
+ _Note: Requires `signer` to be provided on `IO.init` to sign the transaction._
673
+
674
+ ```typescript
675
+ const io = IO.init({ signer: new ArweaveSigner(jwk) });
676
+ const { id: txId } = await io.updateGatewaySettings(
677
+ {
678
+ // any other settings you want to update
679
+ minDelegatedStake: new IOToken(100).toMIO(),
680
+ },
681
+ // optional additional tags
682
+ { tags: [{ name: 'App-Name', value: 'My-Awesome-App' }] },
683
+ );
635
684
  ```
636
685
 
637
- </details>
686
+ #### `increaseDelegateStake({ target, qty })`
638
687
 
639
- #### `getArNSRecords({ cursor, limit, sortBy, sortOrder })`
688
+ Increases the callers stake on the target gateway.
640
689
 
641
- 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.
690
+ _Note: Requires `signer` to be provided on `IO.init` to sign the transaction._
691
+
692
+ ```typescript
693
+ const io = IO.init({ signer: new ArweaveSigner(jwk) });
694
+ const { id: txId } = await io.increaseDelegateStake(
695
+ {
696
+ target: 't4Xr0_J4Iurt7caNST02cMotaz2FIbWQ4Kbj616RHl3',
697
+ qty: new IOToken(100).toMIO(),
698
+ },
699
+ // optional additional tags
700
+ { tags: [{ name: 'App-Name', value: 'My-Awesome-App' }] },
701
+ );
702
+ ```
703
+
704
+ #### `decreaseDelegateStake({ target, qty, instant })`
705
+
706
+ Decreases the callers stake on the target gateway. Can instantly decrease stake by setting instant to `true`.
707
+
708
+ _Note: Requires `signer` to be provided on `IO.init` to sign the transaction._
709
+
710
+ ```typescript
711
+ const io = IO.init({ signer: new ArweaveSigner(jwk) });
712
+ const { id: txId } = await io.decreaseDelegateStake(
713
+ {
714
+ target: 't4Xr0_J4Iurt7caNST02cMotaz2FIbWQ4Kbj616RHl3',
715
+ qty: new IOToken(100).toMIO(),
716
+ },
717
+ {
718
+ tags: [{ name: 'App-Name', value: 'My-Awesome-App' }],
719
+ },
720
+ );
721
+ ```
722
+
723
+ Pay the early withdrawal fee and withdraw instantly.
724
+
725
+ ```typescript
726
+ const io = IO.init({ signer: new ArweaveSigner(jwk) });
727
+ const { id: txId } = await io.decreaseDelegateStake({
728
+ target: 't4Xr0_J4Iurt7caNST02cMotaz2FIbWQ4Kbj616RHl3',
729
+ qty: new IOToken(100).toMIO(),
730
+ instant: true, // Immediately withdraw this stake and pay the instant withdrawal fee
731
+ });
732
+ ```
733
+
734
+ #### `getDelegations({ address, cursor, limit, sortBy, sortOrder })`
735
+
736
+ 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.
642
737
 
643
738
  ```typescript
644
739
  const io = IO.init();
645
- // get the newest 100 names
646
- const records = await io.getArNSRecords({
647
- limit: 100,
740
+ const vaults = await io.getDelegations({
741
+ address: 't4Xr0_J4Iurt7caNST02cMotaz2FIbWQ4Kbj616RHl3',
742
+ cursor: 'QGWqtJdLLgm2ehFWiiPzMaoFLD50CnGuzZIPEdoDRGQ_123456789',
743
+ limit: 2,
648
744
  sortBy: 'startTimestamp',
649
- sortOrder: 'desc',
745
+ sortOrder: 'asc',
650
746
  });
651
747
  ```
652
748
 
653
- Available `sortBy` options are any of the keys on the record object, e.g. `name`, `processId`, `endTimestamp`, `startTimestamp`, `type`, `undernames`.
654
-
655
749
  <details>
656
750
  <summary>Output</summary>
657
751
 
658
752
  ```json
659
753
  {
754
+ "sortOrder": "asc",
755
+ "hasMore": true,
756
+ "totalItems": 95,
757
+ "limit": 2,
758
+ "sortBy": "startTimestamp",
660
759
  "items": [
661
760
  {
662
- "name": "ao",
663
- "processId": "eNey-H9RB9uCdoJUvPULb35qhZVXZcEXv8xds4aHhkQ",
664
- "purchasePrice": 75541282285,
665
- "startTimestamp": 1720720621424,
666
- "type": "permabuy",
667
- "undernames": 10
668
- },
669
- {
670
- "name": "ardrive",
671
- "processId": "bh9l1cy0aksiL_x9M359faGzM_yjralacHIUo8_nQXM",
672
- "endTimestamp": 1720720819969,
673
- "startTimestamp": 1720720620813,
674
- "type": "lease",
675
- "undernames": 100
676
- },
677
- {
678
- "name": "arweave",
679
- "processId": "bh9l1cy0aksiL_x9M359faGzM_yjralacHIUo8_nQXM",
680
- "endTimestamp": 1720720819969,
681
- "startTimestamp": 1720720620800,
682
- "type": "lease",
683
- "undernames": 100
684
- },
685
- {
686
- "name": "ar-io",
687
- "processId": "bh9l1cy0aksiL_x9M359faGzM_yjralacHIUo8_nQXM",
688
- "endTimestamp": 1720720819969,
689
- "startTimestamp": 1720720619000,
690
- "type": "lease",
691
- "undernames": 100
761
+ "type": "stake",
762
+ "startTimestamp": 1727815440632,
763
+ "gatewayAddress": "QGWqtJdLLgm2ehFWiiPzMaoFLD50CnGuzZIPEdoDRGQ",
764
+ "delegationId": "QGWqtJdLLgm2ehFWiiPzMaoFLD50CnGuzZIPEdoDRGQ_1727815440632",
765
+ "balance": 1383212512
692
766
  },
693
767
  {
694
- "name": "fwd",
695
- "processId": "bh9l1cy0aksiL_x9M359faGzM_yjralacHIUo8_nQXM",
696
- "endTimestamp": 1720720819969,
697
- "startTimestamp": 1720720220811,
698
- "type": "lease",
699
- "undernames": 100
768
+ "type": "vault",
769
+ "startTimestamp": 1730996691117,
770
+ "gatewayAddress": "QGWqtJdLLgm2ehFWiiPzMaoFLD50CnGuzZIPEdoDRGQ",
771
+ "delegationId": "QGWqtJdLLgm2ehFWiiPzMaoFLD50CnGuzZIPEdoDRGQ_1730996691117",
772
+ "vaultId": "_sGDS7X1hyLCVpfe40GWioH9BSOb7f0XWbhHBa1q4-g",
773
+ "balance": 50000000,
774
+ "endTimestamp": 1733588691117
700
775
  }
701
- // ...95 other records
702
776
  ],
703
- "hasMore": true,
704
- "nextCursor": "fwdresearch",
705
- "totalItems": 21740,
706
- "sortBy": "startTimestamp",
707
- "sortOrder": "desc"
777
+ "nextCursor": "QGWqtJdLLgm2ehFWiiPzMaoFLD50CnGuzZIPEdoDRGQ_1730996691117"
708
778
  }
709
779
  ```
710
780
 
711
781
  </details>
712
782
 
713
- #### `getArNSAuctions({ cursor, limit, sortBy, sortOrder })`
783
+ #### `instantWithdrawal({ gatewayAddress, vaultId })`
714
784
 
715
- Retrieves all active auctions of the IO process, paginated and sorted by the specified criteria. The `cursor` used for pagination is the last auction name from the previous request.
785
+ Instantly withdraws an existing vault on a gateway. If no `gatewayAddress` is provided, the signer's address will be used.
786
+
787
+ _Note: Requires `signer` to be provided on `IO.init` to sign the transaction._
716
788
 
717
789
  ```typescript
718
- const io = IO.init();
719
- const auctions = await io.getArNSAuctions({
720
- limit: 100,
721
- sortBy: 'endTimestamp',
722
- sortOrder: 'asc', // return the auctions ending soonest first
723
- });
790
+ const io = IO.init({ signer: new ArweaveSigner(jwk) });
791
+ // removes a delegated vault from a gateway
792
+ const { id: txId } = await io.instantWithdrawal(
793
+ {
794
+ // gateway address where delegate vault exists
795
+ gatewayAddress: 't4Xr0_J4Iurt7caNST02cMotaz2FIbWQ4Kbj616RHl3',
796
+ // delegated vault id to cancel
797
+ vaultId: 'fDrr0_J4Iurt7caNST02cMotaz2FIbWQ4Kcj616RHl3',
798
+ },
799
+ // optional additional tags
800
+ {
801
+ tags: [{ name: 'App-Name', value: 'My-Awesome-App' }],
802
+ },
803
+ );
804
+ // removes an operator vault from a gateway
805
+ const { id: txId } = await io.instantWithdrawal(
806
+ {
807
+ vaultId: 'fDrr0_J4Iurt7caNST02cMotaz2FIbWQ4Kcj616RHl3',
808
+ },
809
+ );
724
810
  ```
725
811
 
726
- <details>
727
- <summary>Output</summary>
812
+ #### `cancelWithdrawal({ gatewayAddress, vaultId })`
728
813
 
729
- ```json
730
- {
731
- "items": [
732
- {
733
- "name": "permalink",
734
- "endTimestamp": 1730985241349,
735
- "startTimestamp": 1729775641349,
736
- "baseFee": 250000000,
737
- "demandFactor": 1.05256,
738
- "initiator": "GaQrvEMKBpkjofgnBi_B3IgIDmY_XYelVLB6GcRGrHc",
739
- "settings": {
740
- "durationMs": 1209600000,
741
- "decayRate": 0.000000000016847809193121693,
742
- "scalingExponent": 190,
743
- "startPriceMultiplier": 50
744
- }
745
- }
746
- ],
747
- "hasMore": false,
748
- "totalItems": 1,
749
- "sortBy": "endTimestamp",
750
- "sortOrder": "asc"
751
- }
752
- ```
814
+ Cancels an existing vault on a gateway. The vaulted stake will be returned to the callers stake. If no `gatewayAddress` is provided, the signer's address will be used.
753
815
 
754
- </details>
816
+ _Note: Requires `signer` to be provided on `IO.init` to sign the transaction._
755
817
 
756
- #### `getArNSAuction({ name })`
818
+ ```typescript
819
+ const io = IO.init({ signer: new ArweaveSigner(jwk) });
820
+ // cancels a delegated vault from a gateway
821
+ const { id: txId } = await io.cancelWithdrawal(
822
+ {
823
+ // gateway address where vault exists
824
+ gatewayAddress: 't4Xr0_J4Iurt7caNST02cMotaz2FIbWQ4Kbj616RHl3',
825
+ // vault id to cancel
826
+ vaultId: 'fDrr0_J4Iurt7caNST02cMotaz2FIbWQ4Kcj616RHl3',
827
+ },
828
+ // optional additional tags
829
+ { tags: [{ name: 'App-Name', value: 'My-Awesome-App' }] },
830
+ );
831
+ // cancels an operator vault from a gateway
832
+ const { id: txId } = await io.cancelWithdrawal(
833
+ {
834
+ // operator vault id to cancel
835
+ vaultId: 'fDrr0_J4Iurt7caNST02cMotaz2FIbWQ4Kcj616RHl3',
836
+ },
837
+ );
838
+ ```
757
839
 
758
- Retrieves the auction data for the specified auction name.
840
+ #### `getAllowedDelegates({ address, cursor, limit, sortBy, sortOrder })`
841
+
842
+ Retrieves all allowed delegates for a specific address. The `cursor` used for pagination is the last address from the previous request.
759
843
 
760
844
  ```typescript
761
845
  const io = IO.init();
762
- const auction = await io.getArNSAuction({ name: 'permalink' });
846
+ const allowedDelegates = await io.getAllowedDelegates({
847
+ address: 'QGWqtJdLLgm2ehFWiiPzMaoFLD50CnGuzZIPEdoDRGQ',
848
+ });
763
849
  ```
764
850
 
765
851
  <details>
@@ -767,34 +853,29 @@ const auction = await io.getArNSAuction({ name: 'permalink' });
767
853
 
768
854
  ```json
769
855
  {
770
- "name": "permalink",
771
- "endTimestamp": 1730985241349,
772
- "startTimestamp": 1729775641349,
773
- "baseFee": 250000000,
774
- "demandFactor": 1.05256,
775
- "initiator": "GaQrvEMKBpkjofgnBi_B3IgIDmY_XYelVLB6GcRGrHc",
776
- "settings": {
777
- "durationMs": 1209600000,
778
- "decayRate": 0.000000000016847809193121693,
779
- "scalingExponent": 190,
780
- "startPriceMultiplier": 50
781
- }
856
+ "sortOrder": "desc",
857
+ "hasMore": false,
858
+ "totalItems": 4,
859
+ "limit": 100,
860
+ "items": [
861
+ "PZ5vIhHf8VY969TxBPQN-rYY9CNFP9ggNsMBqlWUzWM",
862
+ "N4h8M9A9hasa3tF47qQyNvcKjm4APBKuFs7vqUVm-SI",
863
+ "JcC4ZLUY76vmWha5y6RwKsFqYTrMZhbockl8iM9p5lQ",
864
+ "31LPFYoow2G7j-eSSsrIh8OlNaARZ84-80J-8ba68d8"
865
+ ]
782
866
  }
783
867
  ```
784
868
 
785
869
  </details>
786
870
 
787
- #### `getArNSAuctionPrices({ name, type, years, intervalMs })`
871
+ #### `getGatewayVaults({ address, cursor, limit, sortBy, sortOrder })`
788
872
 
789
- Retrieves the auction price curve of the specified auction name for the specified type, duration, and interval. The `intervalMs` is the number of milliseconds between price points on the curve. The default interval is 15 minutes.
873
+ Retrieves all vaults across all gateways for a specific address, paginated and sorted by the specified criteria. The `cursor` used for pagination is the last vaultId from the previous request.
790
874
 
791
875
  ```typescript
792
876
  const io = IO.init();
793
- const priceCurve = await io.getArNSAuctionPrices({
794
- name: 'permalink',
795
- type: 'lease',
796
- years: 1,
797
- intervalMs: 3600000, // 1 hour price intervals (default is 15 minutes)
877
+ const vaults = await io.getGatewayVaults({
878
+ address: '"PZ5vIhHf8VY969TxBPQN-rYY9CNFP9ggNsMBqlWUzWM',
798
879
  });
799
880
  ```
800
881
 
@@ -803,68 +884,88 @@ const priceCurve = await io.getArNSAuctionPrices({
803
884
 
804
885
  ```json
805
886
  {
806
- "name": "permalink",
807
- "type": "lease",
808
- "currentPrice": 12582015000,
809
- "years": 1,
810
- "prices": {
811
- "1730412841349": 1618516789,
812
- "1729908841349": 8210426826,
813
- "1730722441349": 592768907,
814
- "1730859241349": 379659914,
815
- "1730866441349": 370850139,
816
- "1730884441349": 349705277,
817
- "1730150041349": 3780993370,
818
- "1730031241349": 5541718397,
819
- "1730603641349": 872066253,
820
- "1730715241349": 606815377,
821
- "1730942041349": 289775172,
822
- "1730916841349": 314621977,
823
- "1730484841349": 1281957300,
824
- "1730585641349": 924535164,
825
- "1730232841349": 2895237473,
826
- "1730675641349": 690200977,
827
- "1730420041349": 1581242331,
828
- "1729786441349": 12154428186,
829
- "1730308441349": 2268298483,
830
- "1730564041349": 991657913,
831
- "1730081641349": 4712427282,
832
- "1730909641349": 322102563,
833
- "1730945641349": 286388732,
834
- "1730024041349": 5671483398,
835
- "1729937641349": 7485620175
836
- // ...
837
- }
887
+ "sortOrder": "desc",
888
+ "hasMore": false,
889
+ "totalItems": 1,
890
+ "limit": 100,
891
+ "sortBy": "endTimestamp",
892
+ "items": [
893
+ {
894
+ "cursorId": "PZ5vIhHf8VY969TxBPQN-rYY9CNFP9ggNsMBqlWUzWM_1728067635857",
895
+ "startTimestamp": 1728067635857,
896
+ "balance": 50000000000,
897
+ "vaultId": "PZ5vIhHf8VY969TxBPQN-rYY9CNFP9ggNsMBqlWUzWM",
898
+ "endTimestamp": 1735843635857
899
+ }
900
+ ]
838
901
  }
839
902
  ```
840
903
 
841
904
  </details>
842
905
 
843
- #### `getDemandFactor()`
906
+ #### `increaseOperatorStake({ qty })`
844
907
 
845
- Retrieves the current demand factor of the network. The demand factor is a multiplier applied to the cost of ArNS interactions based on the current network demand.
908
+ Increases the callers operator stake. Must be executed with a wallet registered as a gateway operator.
909
+
910
+ _Note: Requires `signer` to be provided on `IO.init` to sign the transaction._
846
911
 
847
912
  ```typescript
848
- const io = IO.init();
849
- const demandFactor = await io.getDemandFactor();
913
+ const io = IO.init({ signer: new ArweaveSigner(jwk) });
914
+ const { id: txId } = await io.increaseOperatorStake(
915
+ {
916
+ qty: new IOToken(100).toMIO(),
917
+ },
918
+ {
919
+ tags: [{ name: 'App-Name', value: 'My-Awesome-App' }],
920
+ },
921
+ );
850
922
  ```
851
923
 
852
- <details>
853
- <summary>Output</summary>
924
+ #### `decreaseOperatorStake({ qty })`
854
925
 
855
- ```json
856
- 1.05256
926
+ Decreases the callers operator stake. Must be executed with a wallet registered as a gateway operator. Requires `signer` to be provided on `IO.init` to sign the transaction.
927
+
928
+ _Note: Requires `signer` to be provided on `IO.init` to sign the transaction._
929
+
930
+ ```typescript
931
+ const io = IO.init({ signer: new ArweaveSigner(jwk) });
932
+ const { id: txId } = await io.decreaseOperatorStake(
933
+ {
934
+ qty: new IOToken(100).toMIO(),
935
+ },
936
+ {
937
+ tags: [{ name: 'App-Name', value: 'My-Awesome-App' }],
938
+ },
939
+ );
857
940
  ```
858
941
 
859
- </details>
942
+ #### `redelegateStake({ target, source, stakeQty, vaultId })`
860
943
 
861
- #### `getObservations({ epochIndex })`
944
+ Redelegates the stake of a specific address to a new gateway. Vault ID may be optionally included in order to redelegate from an existing withdrawal vault. The redelegation fee is calculated based on the fee rate and the stake amount. Users are allowed one free redelegation every seven epochs. Each additional redelegation beyond the free redelegation will increase the fee by 10%, capping at a 60% redelegation fee.
862
945
 
863
- Returns the epoch-indexed observation list. If no epoch index is provided, the current epoch is used.
946
+ e.g: If 1000 mIO is redelegated and the fee rate is 10%, the fee will be 100 mIO. Resulting in 900 mIO being redelegated to the new gateway and 100 mIO being deducted back to the protocol balance.
947
+
948
+ ```typescript
949
+ const io = IO.init({ signer: new ArweaveSigner(jwk) });
950
+
951
+ const { id: txId } = await io.redelegateStake({
952
+ target: 't4Xr0_J4Iurt7caNST02cMotaz2FIbWQ4Kbj616RHl3',
953
+ source: 'HwFceQaMQnOBgKDpnFqCqgwKwEU5LBme1oXRuQOWSRA',
954
+ stakeQty: new IOToken(1000).toMIO(),
955
+ vaultId: 'fDrr0_J4Iurt7caNST02cMotaz2FIbWQ4Kcj616RHl3',
956
+ });
957
+ ```
958
+
959
+ #### `getRedelegationFee({ address })`
960
+
961
+ Retrieves the fee rate as percentage required to redelegate the stake of a specific address. Fee rate ranges from 0% to 60% based on the number of redelegations since the last fee reset.
864
962
 
865
963
  ```typescript
866
964
  const io = IO.init();
867
- const observations = await io.getObservations();
965
+
966
+ const fee = await io.getRedelegationFee({
967
+ address: 't4Xr0_J4Iurt7caNST02cMotaz2FIbWQ4Kbj616RHl3',
968
+ });
868
969
  ```
869
970
 
870
971
  <details>
@@ -872,68 +973,39 @@ const observations = await io.getObservations();
872
973
 
873
974
  ```json
874
975
  {
875
- "0": {
876
- "failureSummaries": {
877
- "-Tk2DDk8k4zkwtppp_XFKKI5oUgh6IEHygAoN7mD-w8": [
878
- "Ie2wEEUDKoU26c7IuckHNn3vMFdNQnMvfPBrFzAb3NA",
879
- "Ie2wEEUDKoU26c7IuckHNn3vMFdNQnMvfPBrFzAb3NA"
880
- ]
881
- },
882
- "reports": {
883
- "IPdwa3Mb_9pDD8c2IaJx6aad51Ss-_TfStVwBuhtXMs": "B6UUjKWjjEWDBvDSMXWNmymfwvgR9EN27z5FTkEVlX4",
884
- "Ie2wEEUDKoU26c7IuckHNn3vMFdNQnMvfPBrFzAb3NA": "7tKsiQ2fxv0D8ZVN_QEv29fZ8hwFIgHoEDrpeEG0DIs",
885
- "osZP4D9cqeDvbVFBaEfjIxwc1QLIvRxUBRAxDIX9je8": "aatgznEvC_UPcxp1v0uw_RqydhIfKm4wtt1KCpONBB0",
886
- "qZ90I67XG68BYIAFVNfm9PUdM7v1XtFTn7u-EOZFAtk": "Bd8SmFK9-ktJRmwIungS8ur6JM-JtpxrvMtjt5JkB1M"
887
- }
888
- }
976
+ "redelegationFeeRate": 10,
977
+ "feeResetTimestamp": 1730996691117
889
978
  }
890
979
  ```
891
980
 
892
981
  </details>
893
982
 
894
- #### `getDistributions({ epochIndex })`
983
+ ### Arweave Name System (ArNS)
895
984
 
896
- Returns the current rewards distribution information. If no epoch index is provided, the current epoch is used.
985
+ #### `buyRecord({ name, type, years, processId })`
897
986
 
898
- ```typescript
899
- const io = IO.init();
900
- const distributions = await io.getDistributions({ epochIndex: 0 });
901
- ```
987
+ Purchases a new ArNS record with the specified name, type, and duration.
902
988
 
903
- <details>
904
- <summary>Output</summary>
989
+ _Note: Requires `signer` to be provided on `IO.init` to sign the transaction._
905
990
 
906
- ```json
907
- {
908
- "totalEligibleGateways": 1,
909
- "totalEligibleRewards": 100000000,
910
- "totalEligibleObserverReward": 100000000,
911
- "totalEligibleGatewayReward": 100000000,
912
- "totalDistributedRewards": 100000000,
913
- "distributedTimestamp": 1720720621424,
914
- "rewards": {
915
- "eligible": {
916
- "IPdwa3Mb_9pDD8c2IaJx6aad51Ss-_TfStVwBuhtXMs": {
917
- "operatorReward": 100000000,
918
- "delegateRewards": {}
919
- }
920
- },
921
- "distributed": {
922
- "IPdwa3Mb_9pDD8c2IaJx6aad51Ss-_TfStVwBuhtXMs": 100000000
923
- }
924
- }
925
- }
991
+ ```typescript
992
+ const io = IO.init({ processId: IO_DEVNET_PROCESS_ID, signer });
993
+ const record = await io.buyRecord(
994
+ { name: 'ardrive', type: 'lease', years: 1 },
995
+ {
996
+ // optional tags
997
+ tags: [{ name: 'App-Name', value: 'ArNS-App' }],
998
+ },
999
+ );
926
1000
  ```
927
1001
 
928
- </details>
929
-
930
- #### `getEpoch({ epochIndex })`
1002
+ #### `getArNSRecord({ name })`
931
1003
 
932
- Returns the epoch data for the specified block height. If no epoch index is provided, the current epoch is used.
1004
+ Retrieves the record info of the specified ArNS name.
933
1005
 
934
1006
  ```typescript
935
1007
  const io = IO.init();
936
- const epoch = await io.getEpoch({ epochIndex: 0 });
1008
+ const record = await io.getArNSRecord({ name: 'ardrive' });
937
1009
  ```
938
1010
 
939
1011
  <details>
@@ -941,147 +1013,124 @@ const epoch = await io.getEpoch({ epochIndex: 0 });
941
1013
 
942
1014
  ```json
943
1015
  {
944
- "epochIndex": 0,
945
- "startTimestamp": 1720720620813,
1016
+ "processId": "bh9l1cy0aksiL_x9M359faGzM_yjralacHIUo8_nQXM",
946
1017
  "endTimestamp": 1752256702026,
947
- "startHeight": 1350700,
948
- "distributionTimestamp": 1752256702026,
949
- "observations": {
950
- "failureSummaries": {
951
- "-Tk2DDk8k4zkwtppp_XFKKI5oUgh6IEHygAoN7mD-w8": [
952
- "Ie2wEEUDKoU26c7IuckHNn3vMFdNQnMvfPBrFzAb3NA"
953
- ]
954
- },
955
- "reports": {
956
- "IPdwa3Mb_9pDD8c2IaJx6aad51Ss-_TfStVwBuhtXMs": "B6UUjKWjjEWDBvDSMXWNmymfwvgR9EN27z5FTkEVlX4"
957
- }
958
- },
959
- "prescribedNames": ["ardrive", "ar-io", "arweave", "fwd", "ao"],
960
- "prescribedObservers": [
961
- {
962
- "gatewayAddress": "2Fk8lCmDegPg6jjprl57-UCpKmNgYiKwyhkU4vMNDnE",
963
- "observerAddress": "2Fk8lCmDegPg6jjprl57-UCpKmNgYiKwyhkU4vMNDnE",
964
- "stake": 10000000000, // value in mIO
965
- "startTimestamp": 1720720620813,
966
- "stakeWeight": 1,
967
- "tenureWeight": 0.4494598765432099,
968
- "gatewayRewardRatioWeight": 1,
969
- "observerRewardRatioWeight": 1,
970
- "compositeWeight": 0.4494598765432099,
971
- "normalizedCompositeWeight": 0.002057032496835938
972
- }
973
- ],
974
- "distributions": {
975
- "totalEligibleGateways": 1,
976
- "totalEligibleRewards": 100000000,
977
- "totalEligibleObserverReward": 100000000,
978
- "totalEligibleGatewayReward": 100000000,
979
- "totalDistributedRewards": 100000000,
980
- "distributedTimestamp": 1720720621424,
981
- "rewards": {
982
- "eligible": {
983
- "IPdwa3Mb_9pDD8c2IaJx6aad51Ss-_TfStVwBuhtXMs": {
984
- "operatorReward": 100000000,
985
- "delegateRewards": {}
986
- }
987
- },
988
- "distributed": {
989
- "IPdwa3Mb_9pDD8c2IaJx6aad51Ss-_TfStVwBuhtXMs": 100000000
990
- }
991
- }
992
- }
1018
+ "startTimestamp": 1720720819969,
1019
+ "type": "lease",
1020
+ "undernames": 100
993
1021
  }
994
1022
  ```
995
1023
 
996
1024
  </details>
997
1025
 
998
- #### `getCurrentEpoch()`
1026
+ #### `getArNSRecords({ cursor, limit, sortBy, sortOrder })`
999
1027
 
1000
- Returns the current epoch data.
1028
+ 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.
1001
1029
 
1002
1030
  ```typescript
1003
1031
  const io = IO.init();
1004
- const epoch = await io.getCurrentEpoch();
1032
+ // get the newest 100 names
1033
+ const records = await io.getArNSRecords({
1034
+ limit: 100,
1035
+ sortBy: 'startTimestamp',
1036
+ sortOrder: 'desc',
1037
+ });
1005
1038
  ```
1006
1039
 
1040
+ Available `sortBy` options are any of the keys on the record object, e.g. `name`, `processId`, `endTimestamp`, `startTimestamp`, `type`, `undernames`.
1041
+
1007
1042
  <details>
1008
1043
  <summary>Output</summary>
1009
1044
 
1010
1045
  ```json
1011
1046
  {
1012
- "epochIndex": 0,
1013
- "startTimestamp": 1720720621424,
1014
- "endTimestamp": 1752256702026,
1015
- "startHeight": 1350700,
1016
- "distributionTimestamp": 1711122739,
1017
- "observations": {
1018
- "failureSummaries": {
1019
- "-Tk2DDk8k4zkwtppp_XFKKI5oUgh6IEHygAoN7mD-w8": [
1020
- "Ie2wEEUDKoU26c7IuckHNn3vMFdNQnMvfPBrFzAb3NA"
1021
- ]
1047
+ "items": [
1048
+ {
1049
+ "name": "ao",
1050
+ "processId": "eNey-H9RB9uCdoJUvPULb35qhZVXZcEXv8xds4aHhkQ",
1051
+ "purchasePrice": 75541282285,
1052
+ "startTimestamp": 1720720621424,
1053
+ "type": "permabuy",
1054
+ "undernames": 10
1022
1055
  },
1023
- "reports": {
1024
- "IPdwa3Mb_9pDD8c2IaJx6aad51Ss-_TfStVwBuhtXMs": "B6UUjKWjjEWDBvDSMXWNmymfwvgR9EN27z5FTkEVlX4"
1025
- }
1026
- },
1027
- "prescribedNames": ["ardrive", "ar-io", "arweave", "fwd", "ao"],
1028
- "prescribedObservers": [
1029
1056
  {
1030
- "gatewayAddress": "2Fk8lCmDegPg6jjprl57-UCpKmNgYiKwyhkU4vMNDnE",
1031
- "observerAddress": "2Fk8lCmDegPg6jjprl57-UCpKmNgYiKwyhkU4vMNDnE",
1032
- "stake": 10000000000,
1033
- "start": 1292450,
1034
- "stakeWeight": 1,
1035
- "tenureWeight": 0.4494598765432099,
1036
- "gatewayRewardRatioWeight": 1,
1037
- "observerRewardRatioWeight": 1,
1038
- "compositeWeight": 0.4494598765432099,
1039
- "normalizedCompositeWeight": 0.002057032496835938
1057
+ "name": "ardrive",
1058
+ "processId": "bh9l1cy0aksiL_x9M359faGzM_yjralacHIUo8_nQXM",
1059
+ "endTimestamp": 1720720819969,
1060
+ "startTimestamp": 1720720620813,
1061
+ "type": "lease",
1062
+ "undernames": 100
1063
+ },
1064
+ {
1065
+ "name": "arweave",
1066
+ "processId": "bh9l1cy0aksiL_x9M359faGzM_yjralacHIUo8_nQXM",
1067
+ "endTimestamp": 1720720819969,
1068
+ "startTimestamp": 1720720620800,
1069
+ "type": "lease",
1070
+ "undernames": 100
1071
+ },
1072
+ {
1073
+ "name": "ar-io",
1074
+ "processId": "bh9l1cy0aksiL_x9M359faGzM_yjralacHIUo8_nQXM",
1075
+ "endTimestamp": 1720720819969,
1076
+ "startTimestamp": 1720720619000,
1077
+ "type": "lease",
1078
+ "undernames": 100
1079
+ },
1080
+ {
1081
+ "name": "fwd",
1082
+ "processId": "bh9l1cy0aksiL_x9M359faGzM_yjralacHIUo8_nQXM",
1083
+ "endTimestamp": 1720720819969,
1084
+ "startTimestamp": 1720720220811,
1085
+ "type": "lease",
1086
+ "undernames": 100
1040
1087
  }
1088
+ // ...95 other records
1041
1089
  ],
1042
- "distributions": {
1043
- "distributedTimestamp": 1711122739,
1044
- "totalEligibleRewards": 100000000,
1045
- "rewards": {
1046
- "IPdwa3Mb_9pDD8c2IaJx6aad51Ss-_TfStVwBuhtXMs": 100000000
1047
- }
1048
- }
1090
+ "hasMore": true,
1091
+ "nextCursor": "fwdresearch",
1092
+ "totalItems": 21740,
1093
+ "sortBy": "startTimestamp",
1094
+ "sortOrder": "desc"
1049
1095
  }
1050
1096
  ```
1051
1097
 
1052
1098
  </details>
1053
1099
 
1054
- #### `getPrescribedObservers({ epochIndex })`
1100
+ #### `increaseUndernameLimit({ name, qty })`
1055
1101
 
1056
- Retrieves the prescribed observers of the IO process. To fetch prescribed observers for a previous epoch set the `epochIndex` to the desired epoch index.
1102
+ Increases the undername support of a domain up to a maximum of 10k. Domains, by default, support up to 10 undernames.
1103
+
1104
+ _Note: Requires `signer` to be provided on `IO.init` to sign the transaction._
1057
1105
 
1058
1106
  ```typescript
1059
- const io = IO.init();
1060
- const observers = await io.getPrescribedObservers({ epochIndex: 0 });
1107
+ const io = IO.init({ signer: new ArweaveSigner(jwk) });
1108
+ const { id: txId } = await io.increaseUndernameLimit(
1109
+ {
1110
+ name: 'ar-io',
1111
+ qty: 420,
1112
+ },
1113
+ // optional additional tags
1114
+ { tags: [{ name: 'App-Name', value: 'My-Awesome-App' }] },
1115
+ );
1061
1116
  ```
1062
1117
 
1063
- <details>
1064
- <summary>Output</summary>
1118
+ #### `extendLease({ name, years })`
1065
1119
 
1066
- ```json
1067
- [
1120
+ Extends the lease of a registered ArNS domain, with an extension of 1-5 years depending on grace period status. Permanently registered domains cannot be extended.
1121
+
1122
+ ```typescript
1123
+ const io = IO.init({ signer: new ArweaveSigner(jwk) });
1124
+ const { id: txId } = await io.extendLease(
1068
1125
  {
1069
- "gatewayAddress": "BpQlyhREz4lNGS-y3rSS1WxADfxPpAuing9Lgfdrj2U",
1070
- "observerAddress": "2Fk8lCmDegPg6jjprl57-UCpKmNgYiKwyhkU4vMNDnE",
1071
- "stake": 10000000000, // value in mIO
1072
- "start": 1296976,
1073
- "stakeWeight": 1,
1074
- "tenureWeight": 0.41453703703703704,
1075
- "gatewayRewardRatioWeight": 1,
1076
- "observerRewardRatioWeight": 1,
1077
- "compositeWeight": 0.41453703703703704,
1078
- "normalizedCompositeWeight": 0.0018972019546783507
1079
- }
1080
- ]
1126
+ name: 'ar-io',
1127
+ years: 1,
1128
+ },
1129
+ // optional additional tags
1130
+ { tags: [{ name: 'App-Name', value: 'My-Awesome-App' }] },
1131
+ );
1081
1132
  ```
1082
1133
 
1083
- </details>
1084
-
1085
1134
  #### `getTokenCost({ intent, ...args })`
1086
1135
 
1087
1136
  Calculates the price in mIO to perform the interaction in question, eg a 'Buy-record' interaction, where args are the specific params for that interaction.
@@ -1105,127 +1154,109 @@ const price = await io
1105
1154
 
1106
1155
  </details>
1107
1156
 
1108
- #### `joinNetwork(params)`
1109
-
1110
- Joins a gateway to the ar.io network via its associated wallet.
1157
+ #### `getDemandFactor()`
1111
1158
 
1112
- _Note: Requires `signer` to be provided on `IO.init` to sign the transaction._
1159
+ Retrieves the current demand factor of the network. The demand factor is a multiplier applied to the cost of ArNS interactions based on the current network demand.
1113
1160
 
1114
1161
  ```typescript
1115
- const io = IO.init({ signer: new ArweaveSigner(jwk) });
1116
- const { id: txId } = await io.joinNetwork(
1117
- {
1118
- qty: new IOToken(10_000).toMIO(), // minimum operator stake allowed
1119
- autoStake: true, // auto-stake operator rewards to the gateway
1120
- allowDelegatedStaking: true, // allows delegated staking
1121
- minDelegatedStake: new IOToken(100).toMIO(), // minimum delegated stake allowed
1122
- delegateRewardShareRatio: 10, // percentage of rewards to share with delegates (e.g. 10%)
1123
- label: 'john smith', // min 1, max 64 characters
1124
- note: 'The example gateway', // max 256 characters
1125
- properties: 'FH1aVetOoulPGqgYukj0VE0wIhDy90WiQoV3U2PeY44', // Arweave transaction ID containing additional properties of the Gateway
1126
- observerWallet: '0VE0wIhDy90WiQoV3U2PeY44FH1aVetOoulPGqgYukj', // wallet address of the observer, must match OBSERVER_WALLET on the observer
1127
- fqdn: 'example.com', // fully qualified domain name - note: you must own the domain and set the OBSERVER_WALLET on your gateway to match `observerWallet`
1128
- port: 443, // port number
1129
- protocol: 'https', // only 'https' is supported
1130
- },
1131
- // optional additional tags
1132
- { tags: [{ name: 'App-Name', value: 'My-Awesome-App' }] },
1133
- );
1162
+ const io = IO.init();
1163
+ const demandFactor = await io.getDemandFactor();
1134
1164
  ```
1135
1165
 
1136
- #### `leaveNetwork()`
1166
+ <details>
1167
+ <summary>Output</summary>
1137
1168
 
1138
- Sets the gateway as `leaving` on the ar.io network. Requires `signer` to be provided on `IO.init` to sign the transaction. The gateways operator and delegate stakes are vaulted and will be returned after leave periods. The gateway will be removed from the network after the leave period.
1169
+ ```json
1170
+ 1.05256
1171
+ ```
1139
1172
 
1140
- _Note: Requires `signer` to be provided on `IO.init` to sign the transaction._
1141
-
1142
- ```typescript
1143
- const io = IO.init({ signer: new ArweaveSigner(jwk) });
1144
-
1145
- const { id: txId } = await io.leaveNetwork(
1146
- // optional additional tags
1147
- { tags: [{ name: 'App-Name', value: 'My-Awesome-App' }] },
1148
- );
1149
- ```
1150
-
1151
- #### `updateGatewaySettings(gatewaySettings)`
1173
+ </details>
1152
1174
 
1153
- Writes new gateway settings to the callers gateway configuration.
1175
+ #### `getArNSAuctions({ cursor, limit, sortBy, sortOrder })`
1154
1176
 
1155
- _Note: Requires `signer` to be provided on `IO.init` to sign the transaction._
1177
+ Retrieves all active auctions of the IO process, paginated and sorted by the specified criteria. The `cursor` used for pagination is the last auction name from the previous request.
1156
1178
 
1157
1179
  ```typescript
1158
- const io = IO.init({ signer: new ArweaveSigner(jwk) });
1159
- const { id: txId } = await io.updateGatewaySettings(
1160
- {
1161
- // any other settings you want to update
1162
- minDelegatedStake: new IOToken(100).toMIO(),
1163
- },
1164
- // optional additional tags
1165
- { tags: [{ name: 'App-Name', value: 'My-Awesome-App' }] },
1166
- );
1180
+ const io = IO.init();
1181
+ const auctions = await io.getArNSAuctions({
1182
+ limit: 100,
1183
+ sortBy: 'endTimestamp',
1184
+ sortOrder: 'asc', // return the auctions ending soonest first
1185
+ });
1167
1186
  ```
1168
1187
 
1169
- #### `increaseDelegateStake({ target, qty })`
1170
-
1171
- Increases the callers stake on the target gateway.
1172
-
1173
- _Note: Requires `signer` to be provided on `IO.init` to sign the transaction._
1188
+ <details>
1189
+ <summary>Output</summary>
1174
1190
 
1175
- ```typescript
1176
- const io = IO.init({ signer: new ArweaveSigner(jwk) });
1177
- const { id: txId } = await io.increaseDelegateStake(
1178
- {
1179
- target: 't4Xr0_J4Iurt7caNST02cMotaz2FIbWQ4Kbj616RHl3',
1180
- qty: new IOToken(100).toMIO(),
1181
- },
1182
- // optional additional tags
1183
- { tags: [{ name: 'App-Name', value: 'My-Awesome-App' }] },
1184
- );
1191
+ ```json
1192
+ {
1193
+ "items": [
1194
+ {
1195
+ "name": "permalink",
1196
+ "endTimestamp": 1730985241349,
1197
+ "startTimestamp": 1729775641349,
1198
+ "baseFee": 250000000,
1199
+ "demandFactor": 1.05256,
1200
+ "initiator": "GaQrvEMKBpkjofgnBi_B3IgIDmY_XYelVLB6GcRGrHc",
1201
+ "settings": {
1202
+ "durationMs": 1209600000,
1203
+ "decayRate": 0.000000000016847809193121693,
1204
+ "scalingExponent": 190,
1205
+ "startPriceMultiplier": 50
1206
+ }
1207
+ }
1208
+ ],
1209
+ "hasMore": false,
1210
+ "totalItems": 1,
1211
+ "sortBy": "endTimestamp",
1212
+ "sortOrder": "asc"
1213
+ }
1185
1214
  ```
1186
1215
 
1187
- #### `decreaseDelegateStake({ target, qty, instant })`
1216
+ </details>
1188
1217
 
1189
- Decreases the callers stake on the target gateway. Can instantly decrease stake by setting instant to `true`.
1218
+ #### `getArNSAuction({ name })`
1190
1219
 
1191
- _Note: Requires `signer` to be provided on `IO.init` to sign the transaction._
1220
+ Retrieves the auction data for the specified auction name.
1192
1221
 
1193
1222
  ```typescript
1194
- const io = IO.init({ signer: new ArweaveSigner(jwk) });
1195
- const { id: txId } = await io.decreaseDelegateStake(
1196
- {
1197
- target: 't4Xr0_J4Iurt7caNST02cMotaz2FIbWQ4Kbj616RHl3',
1198
- qty: new IOToken(100).toMIO(),
1199
- },
1200
- {
1201
- tags: [{ name: 'App-Name', value: 'My-Awesome-App' }],
1202
- },
1203
- );
1223
+ const io = IO.init();
1224
+ const auction = await io.getArNSAuction({ name: 'permalink' });
1204
1225
  ```
1205
1226
 
1206
- Pay the early withdrawal fee and withdraw instantly.
1227
+ <details>
1228
+ <summary>Output</summary>
1207
1229
 
1208
- ```typescript
1209
- const io = IO.init({ signer: new ArweaveSigner(jwk) });
1210
- const { id: txId } = await io.decreaseDelegateStake({
1211
- target: 't4Xr0_J4Iurt7caNST02cMotaz2FIbWQ4Kbj616RHl3',
1212
- qty: new IOToken(100).toMIO(),
1213
- instant: true, // Immediately withdraw this stake and pay the instant withdrawal fee
1214
- });
1230
+ ```json
1231
+ {
1232
+ "name": "permalink",
1233
+ "endTimestamp": 1730985241349,
1234
+ "startTimestamp": 1729775641349,
1235
+ "baseFee": 250000000,
1236
+ "demandFactor": 1.05256,
1237
+ "initiator": "GaQrvEMKBpkjofgnBi_B3IgIDmY_XYelVLB6GcRGrHc",
1238
+ "settings": {
1239
+ "durationMs": 1209600000,
1240
+ "decayRate": 0.000000000016847809193121693,
1241
+ "scalingExponent": 190,
1242
+ "startPriceMultiplier": 50
1243
+ }
1244
+ }
1215
1245
  ```
1216
1246
 
1217
- #### `getDelegations({ address, cursor, limit, sortBy, sortOrder })`
1247
+ </details>
1218
1248
 
1219
- 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.
1249
+ #### `getArNSAuctionPrices({ name, type, years, intervalMs })`
1250
+
1251
+ Retrieves the auction price curve of the specified auction name for the specified type, duration, and interval. The `intervalMs` is the number of milliseconds between price points on the curve. The default interval is 15 minutes.
1220
1252
 
1221
1253
  ```typescript
1222
1254
  const io = IO.init();
1223
- const vaults = await io.getDelegations({
1224
- address: 't4Xr0_J4Iurt7caNST02cMotaz2FIbWQ4Kbj616RHl3',
1225
- cursor: 'QGWqtJdLLgm2ehFWiiPzMaoFLD50CnGuzZIPEdoDRGQ_123456789',
1226
- limit: 2,
1227
- sortBy: 'startTimestamp',
1228
- sortOrder: 'asc',
1255
+ const priceCurve = await io.getArNSAuctionPrices({
1256
+ name: 'permalink',
1257
+ type: 'lease',
1258
+ years: 1,
1259
+ intervalMs: 3600000, // 1 hour price intervals (default is 15 minutes)
1229
1260
  });
1230
1261
  ```
1231
1262
 
@@ -1234,75 +1265,78 @@ const vaults = await io.getDelegations({
1234
1265
 
1235
1266
  ```json
1236
1267
  {
1237
- "sortOrder": "asc",
1238
- "hasMore": true,
1239
- "totalItems": 95,
1240
- "limit": 2,
1241
- "sortBy": "startTimestamp",
1242
- "items": [
1243
- {
1244
- "type": "stake",
1245
- "startTimestamp": 1727815440632,
1246
- "gatewayAddress": "QGWqtJdLLgm2ehFWiiPzMaoFLD50CnGuzZIPEdoDRGQ",
1247
- "delegationId": "QGWqtJdLLgm2ehFWiiPzMaoFLD50CnGuzZIPEdoDRGQ_1727815440632",
1248
- "balance": 1383212512
1249
- },
1250
- {
1251
- "type": "vault",
1252
- "startTimestamp": 1730996691117,
1253
- "gatewayAddress": "QGWqtJdLLgm2ehFWiiPzMaoFLD50CnGuzZIPEdoDRGQ",
1254
- "delegationId": "QGWqtJdLLgm2ehFWiiPzMaoFLD50CnGuzZIPEdoDRGQ_1730996691117",
1255
- "vaultId": "_sGDS7X1hyLCVpfe40GWioH9BSOb7f0XWbhHBa1q4-g",
1256
- "balance": 50000000,
1257
- "endTimestamp": 1733588691117
1258
- }
1259
- ],
1260
- "nextCursor": "QGWqtJdLLgm2ehFWiiPzMaoFLD50CnGuzZIPEdoDRGQ_1730996691117"
1268
+ "name": "permalink",
1269
+ "type": "lease",
1270
+ "currentPrice": 12582015000,
1271
+ "years": 1,
1272
+ "prices": {
1273
+ "1730412841349": 1618516789,
1274
+ "1729908841349": 8210426826,
1275
+ "1730722441349": 592768907,
1276
+ "1730859241349": 379659914,
1277
+ "1730866441349": 370850139,
1278
+ "1730884441349": 349705277,
1279
+ "1730150041349": 3780993370,
1280
+ "1730031241349": 5541718397,
1281
+ "1730603641349": 872066253,
1282
+ "1730715241349": 606815377,
1283
+ "1730942041349": 289775172,
1284
+ "1730916841349": 314621977,
1285
+ "1730484841349": 1281957300,
1286
+ "1730585641349": 924535164,
1287
+ "1730232841349": 2895237473,
1288
+ "1730675641349": 690200977,
1289
+ "1730420041349": 1581242331,
1290
+ "1729786441349": 12154428186,
1291
+ "1730308441349": 2268298483,
1292
+ "1730564041349": 991657913,
1293
+ "1730081641349": 4712427282,
1294
+ "1730909641349": 322102563,
1295
+ "1730945641349": 286388732,
1296
+ "1730024041349": 5671483398,
1297
+ "1729937641349": 7485620175
1298
+ // ...
1299
+ }
1261
1300
  }
1262
1301
  ```
1263
1302
 
1264
1303
  </details>
1265
1304
 
1266
- #### `getAllowedDelegates({ address, cursor, limit, sortBy, sortOrder })`
1305
+ #### `submitAuctionBid({ name, type, years, processId })`
1267
1306
 
1268
- Retrieves all allowed delegates for a specific address. The `cursor` used for pagination is the last address from the previous request.
1307
+ Submit a bid for the current auction. If the bid is accepted, the name will be leased for the specified duration and assigned the specified type and processId.
1308
+
1309
+ _Note: Requires `signer` to be provided on `IO.init` to sign the transaction._
1269
1310
 
1270
1311
  ```typescript
1271
- const io = IO.init();
1272
- const allowedDelegates = await io.getAllowedDelegates({
1273
- address: 'QGWqtJdLLgm2ehFWiiPzMaoFLD50CnGuzZIPEdoDRGQ',
1274
- });
1275
- ```
1312
+ const io = IO.init({ signer: new ArweaveSigner(jwk) });
1276
1313
 
1277
- <details>
1278
- <summary>Output</summary>
1314
+ const auction = await io.getArNSAuction({ name: 'permalink' });
1279
1315
 
1280
- ```json
1281
- {
1282
- "sortOrder": "desc",
1283
- "hasMore": false,
1284
- "totalItems": 4,
1285
- "limit": 100,
1286
- "items": [
1287
- "PZ5vIhHf8VY969TxBPQN-rYY9CNFP9ggNsMBqlWUzWM",
1288
- "N4h8M9A9hasa3tF47qQyNvcKjm4APBKuFs7vqUVm-SI",
1289
- "JcC4ZLUY76vmWha5y6RwKsFqYTrMZhbockl8iM9p5lQ",
1290
- "31LPFYoow2G7j-eSSsrIh8OlNaARZ84-80J-8ba68d8"
1291
- ]
1316
+ // check the current price is under some threshold
1317
+ if (auction && auction.currentPrice <= new IOToken(20_000).toMIO().valueOf()) {
1318
+ const { id: txId } = await io.submitAuctionBid(
1319
+ {
1320
+ name: 'permalink',
1321
+ type: 'lease',
1322
+ years: 1,
1323
+ processId: 'bh9l1cy0aksiL_x9M359faGzM_yjralacHIUo8_nQXM',
1324
+ },
1325
+ // optional additional tags
1326
+ { tags: [{ name: 'App-Name', value: 'My-Awesome-App' }] },
1327
+ );
1292
1328
  }
1293
1329
  ```
1294
1330
 
1295
- </details>
1331
+ ### Epochs
1296
1332
 
1297
- #### `getGatewayVaults({ address, cursor, limit, sortBy, sortOrder })`
1333
+ #### `getCurrentEpoch()`
1298
1334
 
1299
- Retrieves all vaults across all gateways for a specific address, paginated and sorted by the specified criteria. The `cursor` used for pagination is the last vaultId from the previous request.
1335
+ Returns the current epoch data.
1300
1336
 
1301
1337
  ```typescript
1302
1338
  const io = IO.init();
1303
- const vaults = await io.getGatewayVaults({
1304
- address: '"PZ5vIhHf8VY969TxBPQN-rYY9CNFP9ggNsMBqlWUzWM',
1305
- });
1339
+ const epoch = await io.getCurrentEpoch();
1306
1340
  ```
1307
1341
 
1308
1342
  <details>
@@ -1310,88 +1344,181 @@ const vaults = await io.getGatewayVaults({
1310
1344
 
1311
1345
  ```json
1312
1346
  {
1313
- "sortOrder": "desc",
1314
- "hasMore": false,
1315
- "totalItems": 1,
1316
- "limit": 100,
1317
- "sortBy": "endTimestamp",
1318
- "items": [
1347
+ "epochIndex": 0,
1348
+ "startTimestamp": 1720720621424,
1349
+ "endTimestamp": 1752256702026,
1350
+ "startHeight": 1350700,
1351
+ "distributionTimestamp": 1711122739,
1352
+ "observations": {
1353
+ "failureSummaries": {
1354
+ "-Tk2DDk8k4zkwtppp_XFKKI5oUgh6IEHygAoN7mD-w8": [
1355
+ "Ie2wEEUDKoU26c7IuckHNn3vMFdNQnMvfPBrFzAb3NA"
1356
+ ]
1357
+ },
1358
+ "reports": {
1359
+ "IPdwa3Mb_9pDD8c2IaJx6aad51Ss-_TfStVwBuhtXMs": "B6UUjKWjjEWDBvDSMXWNmymfwvgR9EN27z5FTkEVlX4"
1360
+ }
1361
+ },
1362
+ "prescribedNames": ["ardrive", "ar-io", "arweave", "fwd", "ao"],
1363
+ "prescribedObservers": [
1319
1364
  {
1320
- "cursorId": "PZ5vIhHf8VY969TxBPQN-rYY9CNFP9ggNsMBqlWUzWM_1728067635857",
1321
- "startTimestamp": 1728067635857,
1322
- "balance": 50000000000,
1323
- "vaultId": "PZ5vIhHf8VY969TxBPQN-rYY9CNFP9ggNsMBqlWUzWM",
1324
- "endTimestamp": 1735843635857
1365
+ "gatewayAddress": "2Fk8lCmDegPg6jjprl57-UCpKmNgYiKwyhkU4vMNDnE",
1366
+ "observerAddress": "2Fk8lCmDegPg6jjprl57-UCpKmNgYiKwyhkU4vMNDnE",
1367
+ "stake": 10000000000,
1368
+ "start": 1292450,
1369
+ "stakeWeight": 1,
1370
+ "tenureWeight": 0.4494598765432099,
1371
+ "gatewayRewardRatioWeight": 1,
1372
+ "observerRewardRatioWeight": 1,
1373
+ "compositeWeight": 0.4494598765432099,
1374
+ "normalizedCompositeWeight": 0.002057032496835938
1325
1375
  }
1326
- ]
1376
+ ],
1377
+ "distributions": {
1378
+ "distributedTimestamp": 1711122739,
1379
+ "totalEligibleRewards": 100000000,
1380
+ "rewards": {
1381
+ "IPdwa3Mb_9pDD8c2IaJx6aad51Ss-_TfStVwBuhtXMs": 100000000
1382
+ }
1383
+ }
1327
1384
  }
1328
1385
  ```
1329
1386
 
1330
1387
  </details>
1331
1388
 
1332
- #### `instantWithdrawal({ gatewayAddress, vaultId })`
1333
-
1334
- Instantly withdraws an existing vault on a gateway. If no `gatewayAddress` is provided, the signer's address will be used.
1389
+ #### `getEpoch({ epochIndex })`
1335
1390
 
1336
- _Note: Requires `signer` to be provided on `IO.init` to sign the transaction._
1391
+ Returns the epoch data for the specified block height. If no epoch index is provided, the current epoch is used.
1337
1392
 
1338
1393
  ```typescript
1339
- const io = IO.init({ signer: new ArweaveSigner(jwk) });
1340
- // removes a delegated vault from a gateway
1341
- const { id: txId } = await io.instantWithdrawal(
1342
- {
1343
- // gateway address where delegate vault exists
1344
- gatewayAddress: 't4Xr0_J4Iurt7caNST02cMotaz2FIbWQ4Kbj616RHl3',
1345
- // delegated vault id to cancel
1346
- vaultId: 'fDrr0_J4Iurt7caNST02cMotaz2FIbWQ4Kcj616RHl3',
1347
- },
1348
- // optional additional tags
1349
- {
1350
- tags: [{ name: 'App-Name', value: 'My-Awesome-App' }],
1351
- },
1352
- );
1353
- // removes an operator vault from a gateway
1354
- const { id: txId } = await io.instantWithdrawal(
1355
- {
1356
- vaultId: 'fDrr0_J4Iurt7caNST02cMotaz2FIbWQ4Kcj616RHl3',
1394
+ const io = IO.init();
1395
+ const epoch = await io.getEpoch({ epochIndex: 0 });
1396
+ ```
1397
+
1398
+ <details>
1399
+ <summary>Output</summary>
1400
+
1401
+ ```json
1402
+ {
1403
+ "epochIndex": 0,
1404
+ "startTimestamp": 1720720620813,
1405
+ "endTimestamp": 1752256702026,
1406
+ "startHeight": 1350700,
1407
+ "distributionTimestamp": 1752256702026,
1408
+ "observations": {
1409
+ "failureSummaries": {
1410
+ "-Tk2DDk8k4zkwtppp_XFKKI5oUgh6IEHygAoN7mD-w8": [
1411
+ "Ie2wEEUDKoU26c7IuckHNn3vMFdNQnMvfPBrFzAb3NA"
1412
+ ]
1413
+ },
1414
+ "reports": {
1415
+ "IPdwa3Mb_9pDD8c2IaJx6aad51Ss-_TfStVwBuhtXMs": "B6UUjKWjjEWDBvDSMXWNmymfwvgR9EN27z5FTkEVlX4"
1416
+ }
1357
1417
  },
1358
- );
1418
+ "prescribedNames": ["ardrive", "ar-io", "arweave", "fwd", "ao"],
1419
+ "prescribedObservers": [
1420
+ {
1421
+ "gatewayAddress": "2Fk8lCmDegPg6jjprl57-UCpKmNgYiKwyhkU4vMNDnE",
1422
+ "observerAddress": "2Fk8lCmDegPg6jjprl57-UCpKmNgYiKwyhkU4vMNDnE",
1423
+ "stake": 10000000000, // value in mIO
1424
+ "startTimestamp": 1720720620813,
1425
+ "stakeWeight": 1,
1426
+ "tenureWeight": 0.4494598765432099,
1427
+ "gatewayRewardRatioWeight": 1,
1428
+ "observerRewardRatioWeight": 1,
1429
+ "compositeWeight": 0.4494598765432099,
1430
+ "normalizedCompositeWeight": 0.002057032496835938
1431
+ }
1432
+ ],
1433
+ "distributions": {
1434
+ "totalEligibleGateways": 1,
1435
+ "totalEligibleRewards": 100000000,
1436
+ "totalEligibleObserverReward": 100000000,
1437
+ "totalEligibleGatewayReward": 100000000,
1438
+ "totalDistributedRewards": 100000000,
1439
+ "distributedTimestamp": 1720720621424,
1440
+ "rewards": {
1441
+ "eligible": {
1442
+ "IPdwa3Mb_9pDD8c2IaJx6aad51Ss-_TfStVwBuhtXMs": {
1443
+ "operatorReward": 100000000,
1444
+ "delegateRewards": {}
1445
+ }
1446
+ },
1447
+ "distributed": {
1448
+ "IPdwa3Mb_9pDD8c2IaJx6aad51Ss-_TfStVwBuhtXMs": 100000000
1449
+ }
1450
+ }
1451
+ }
1452
+ }
1359
1453
  ```
1360
1454
 
1361
- #### `increaseOperatorStake({ qty })`
1455
+ </details>
1362
1456
 
1363
- Increases the callers operator stake. Must be executed with a wallet registered as a gateway operator.
1457
+ #### `getObservations({ epochIndex })`
1364
1458
 
1365
- _Note: Requires `signer` to be provided on `IO.init` to sign the transaction._
1459
+ Returns the epoch-indexed observation list. If no epoch index is provided, the current epoch is used.
1366
1460
 
1367
1461
  ```typescript
1368
- const io = IO.init({ signer: new ArweaveSigner(jwk) });
1369
- const { id: txId } = await io.increaseOperatorStake(
1370
- {
1371
- qty: new IOToken(100).toMIO(),
1372
- },
1373
- {
1374
- tags: [{ name: 'App-Name', value: 'My-Awesome-App' }],
1375
- },
1376
- );
1462
+ const io = IO.init();
1463
+ const observations = await io.getObservations();
1377
1464
  ```
1378
1465
 
1379
- #### `decreaseOperatorStake({ qty })`
1466
+ <details>
1467
+ <summary>Output</summary>
1380
1468
 
1381
- Decreases the callers operator stake. Must be executed with a wallet registered as a gateway operator. Requires `signer` to be provided on `IO.init` to sign the transaction.
1469
+ ```json
1470
+ {
1471
+ "0": {
1472
+ "failureSummaries": {
1473
+ "-Tk2DDk8k4zkwtppp_XFKKI5oUgh6IEHygAoN7mD-w8": [
1474
+ "Ie2wEEUDKoU26c7IuckHNn3vMFdNQnMvfPBrFzAb3NA",
1475
+ "Ie2wEEUDKoU26c7IuckHNn3vMFdNQnMvfPBrFzAb3NA"
1476
+ ]
1477
+ },
1478
+ "reports": {
1479
+ "IPdwa3Mb_9pDD8c2IaJx6aad51Ss-_TfStVwBuhtXMs": "B6UUjKWjjEWDBvDSMXWNmymfwvgR9EN27z5FTkEVlX4",
1480
+ "Ie2wEEUDKoU26c7IuckHNn3vMFdNQnMvfPBrFzAb3NA": "7tKsiQ2fxv0D8ZVN_QEv29fZ8hwFIgHoEDrpeEG0DIs",
1481
+ "osZP4D9cqeDvbVFBaEfjIxwc1QLIvRxUBRAxDIX9je8": "aatgznEvC_UPcxp1v0uw_RqydhIfKm4wtt1KCpONBB0",
1482
+ "qZ90I67XG68BYIAFVNfm9PUdM7v1XtFTn7u-EOZFAtk": "Bd8SmFK9-ktJRmwIungS8ur6JM-JtpxrvMtjt5JkB1M"
1483
+ }
1484
+ }
1485
+ }
1486
+ ```
1382
1487
 
1383
- _Note: Requires `signer` to be provided on `IO.init` to sign the transaction._
1488
+ </details>
1489
+
1490
+ #### `getDistributions({ epochIndex })`
1491
+
1492
+ Returns the current rewards distribution information. If no epoch index is provided, the current epoch is used.
1384
1493
 
1385
1494
  ```typescript
1386
- const io = IO.init({ signer: new ArweaveSigner(jwk) });
1387
- const { id: txId } = await io.decreaseOperatorStake(
1388
- {
1389
- qty: new IOToken(100).toMIO(),
1390
- },
1391
- {
1392
- tags: [{ name: 'App-Name', value: 'My-Awesome-App' }],
1393
- },
1394
- );
1495
+ const io = IO.init();
1496
+ const distributions = await io.getDistributions({ epochIndex: 0 });
1497
+ ```
1498
+
1499
+ <details>
1500
+ <summary>Output</summary>
1501
+
1502
+ ```json
1503
+ {
1504
+ "totalEligibleGateways": 1,
1505
+ "totalEligibleRewards": 100000000,
1506
+ "totalEligibleObserverReward": 100000000,
1507
+ "totalEligibleGatewayReward": 100000000,
1508
+ "totalDistributedRewards": 100000000,
1509
+ "distributedTimestamp": 1720720621424,
1510
+ "rewards": {
1511
+ "eligible": {
1512
+ "IPdwa3Mb_9pDD8c2IaJx6aad51Ss-_TfStVwBuhtXMs": {
1513
+ "operatorReward": 100000000,
1514
+ "delegateRewards": {}
1515
+ }
1516
+ },
1517
+ "distributed": {
1518
+ "IPdwa3Mb_9pDD8c2IaJx6aad51Ss-_TfStVwBuhtXMs": 100000000
1519
+ }
1520
+ }
1521
+ }
1395
1522
  ```
1396
1523
 
1397
1524
  #### `saveObservations({ reportTxId, failedGateways })`
@@ -1413,121 +1540,52 @@ const { id: txId } = await io.saveObservations(
1413
1540
  );
1414
1541
  ```
1415
1542
 
1416
- #### `transfer({ target, qty })`
1417
-
1418
- Transfers `mIO` to the designated `target` recipient address. Requires `signer` to be provided on `IO.init` to sign the transaction.
1419
-
1420
- _Note: Requires `signer` to be provided on `IO.init` to sign the transaction._
1421
-
1422
- ```typescript
1423
- const io = IO.init({ signer: new ArweaveSigner(jwk) });
1424
- const { id: txId } = await io.transfer(
1425
- {
1426
- target: '-5dV7nk7waR8v4STuwPnTck1zFVkQqJh5K9q9Zik4Y5',
1427
- qty: new IOToken(1000).toMIO(),
1428
- },
1429
- // optional additional tags
1430
- { tags: [{ name: 'App-Name', value: 'My-Awesome-App' }] },
1431
- );
1432
- ```
1433
-
1434
- #### `increaseUndernameLimit({ name, qty })`
1435
-
1436
- Increases the undername support of a domain up to a maximum of 10k. Domains, by default, support up to 10 undernames.
1437
-
1438
- _Note: Requires `signer` to be provided on `IO.init` to sign the transaction._
1439
-
1440
- ```typescript
1441
- const io = IO.init({ signer: new ArweaveSigner(jwk) });
1442
- const { id: txId } = await io.increaseUndernameLimit(
1443
- {
1444
- name: 'ar-io',
1445
- qty: 420,
1446
- },
1447
- // optional additional tags
1448
- { tags: [{ name: 'App-Name', value: 'My-Awesome-App' }] },
1449
- );
1450
- ```
1543
+ </details>
1451
1544
 
1452
- #### `extendLease({ name, years })`
1545
+ #### `getPrescribedObservers({ epochIndex })`
1453
1546
 
1454
- Extends the lease of a registered ArNS domain, with an extension of 1-5 years depending on grace period status. Permanently registered domains cannot be extended.
1547
+ Retrieves the prescribed observers of the IO process. To fetch prescribed observers for a previous epoch set the `epochIndex` to the desired epoch index.
1455
1548
 
1456
1549
  ```typescript
1457
- const io = IO.init({ signer: new ArweaveSigner(jwk) });
1458
- const { id: txId } = await io.extendLease(
1459
- {
1460
- name: 'ar-io',
1461
- years: 1,
1462
- },
1463
- // optional additional tags
1464
- { tags: [{ name: 'App-Name', value: 'My-Awesome-App' }] },
1465
- );
1550
+ const io = IO.init();
1551
+ const observers = await io.getPrescribedObservers({ epochIndex: 0 });
1466
1552
  ```
1467
1553
 
1468
- #### `cancelWithdrawal({ gatewayAddress, vaultId })`
1469
-
1470
- Cancels an existing vault on a gateway. The vaulted stake will be returned to the callers stake. If no `gatewayAddress` is provided, the signer's address will be used.
1471
-
1472
- _Note: Requires `signer` to be provided on `IO.init` to sign the transaction._
1554
+ <details>
1555
+ <summary>Output</summary>
1473
1556
 
1474
- ```typescript
1475
- const io = IO.init({ signer: new ArweaveSigner(jwk) });
1476
- // cancels a delegated vault from a gateway
1477
- const { id: txId } = await io.cancelWithdrawal(
1478
- {
1479
- // gateway address where vault exists
1480
- gatewayAddress: 't4Xr0_J4Iurt7caNST02cMotaz2FIbWQ4Kbj616RHl3',
1481
- // vault id to cancel
1482
- vaultId: 'fDrr0_J4Iurt7caNST02cMotaz2FIbWQ4Kcj616RHl3',
1483
- },
1484
- // optional additional tags
1485
- { tags: [{ name: 'App-Name', value: 'My-Awesome-App' }] },
1486
- );
1487
- // cancels an operator vault from a gateway
1488
- const { id: txId } = await io.cancelWithdrawal(
1557
+ ```json
1558
+ [
1489
1559
  {
1490
- // operator vault id to cancel
1491
- vaultId: 'fDrr0_J4Iurt7caNST02cMotaz2FIbWQ4Kcj616RHl3',
1492
- },
1493
- );
1560
+ "gatewayAddress": "BpQlyhREz4lNGS-y3rSS1WxADfxPpAuing9Lgfdrj2U",
1561
+ "observerAddress": "2Fk8lCmDegPg6jjprl57-UCpKmNgYiKwyhkU4vMNDnE",
1562
+ "stake": 10000000000, // value in mIO
1563
+ "start": 1296976,
1564
+ "stakeWeight": 1,
1565
+ "tenureWeight": 0.41453703703703704,
1566
+ "gatewayRewardRatioWeight": 1,
1567
+ "observerRewardRatioWeight": 1,
1568
+ "compositeWeight": 0.41453703703703704,
1569
+ "normalizedCompositeWeight": 0.0018972019546783507
1570
+ }
1571
+ ]
1494
1572
  ```
1495
1573
 
1496
- #### `submitAuctionBid({ name, type, years, processId })`
1497
-
1498
- Submit a bid for the current auction. If the bid is accepted, the name will be leased for the specified duration and assigned the specified type and processId.
1499
-
1500
- _Note: Requires `signer` to be provided on `IO.init` to sign the transaction._
1501
-
1502
- ```typescript
1503
- const io = IO.init({ signer: new ArweaveSigner(jwk) });
1504
-
1505
- const auction = await io.getArNSAuction({ name: 'permalink' });
1574
+ </details>
1506
1575
 
1507
- // check the current price is under some threshold
1508
- if (auction && auction.currentPrice <= new IOToken(20_000).toMIO().valueOf()) {
1509
- const { id: txId } = await io.submitAuctionBid(
1510
- {
1511
- name: 'permalink',
1512
- type: 'lease',
1513
- years: 1,
1514
- processId: 'bh9l1cy0aksiL_x9M359faGzM_yjralacHIUo8_nQXM',
1515
- },
1516
- // optional additional tags
1517
- { tags: [{ name: 'App-Name', value: 'My-Awesome-App' }] },
1518
- );
1519
- }
1520
- ```
1576
+ ### Primary Names
1521
1577
 
1522
1578
  #### `getPrimaryNames({ cursor, limit, sortBy, sortOrder })`
1523
1579
 
1524
- Retrieves all primary names across all gateways, paginated and sorted by the specified criteria. The `cursor` used for pagination is the last name from the previous request.
1580
+ Retrieves all primary names paginated and sorted by the specified criteria. The `cursor` used for pagination is the last name from the previous request.
1525
1581
 
1526
1582
  ```typescript
1527
1583
  const io = IO.init();
1528
1584
  const names = await io.getPrimaryNames({
1529
- cursor: 'ar-io',
1530
- limit: 2,
1585
+ cursor: 'ao', // this is the last name from the previous request
1586
+ limit: 1,
1587
+ sortBy: 'startTimestamp',
1588
+ sortOrder: 'desc',
1531
1589
  });
1532
1590
  ```
1533
1591
 
@@ -1537,10 +1595,10 @@ const names = await io.getPrimaryNames({
1537
1595
  ```json
1538
1596
  {
1539
1597
  "sortOrder": "desc",
1540
- "hasMore": false,
1541
- "totalItems": 1,
1542
- "limit": 100,
1543
- "sortBy": "name",
1598
+ "hasMore": true,
1599
+ "totalItems": 100,
1600
+ "limit": 1,
1601
+ "sortBy": "startTimestamp",
1544
1602
  "items": [
1545
1603
  {
1546
1604
  "owner": "HwFceQaMQnOBgKDpnFqCqgwKwEU5LBme1oXRuQOWSRA",
@@ -1619,47 +1677,6 @@ const request = await io.getPrimaryNameRequest({
1619
1677
 
1620
1678
  </details>
1621
1679
 
1622
- #### `redelegateStake({ target, source, stakeQty, vaultId })`
1623
-
1624
- Redelegates the stake of a specific address to a new gateway. Vault ID may be optionally included in order to redelegate from an existing withdrawal vault. The redelegation fee is calculated based on the fee rate and the stake amount. Users are allowed one free redelegation every seven epochs. Each additional redelegation beyond the free redelegation will increase the fee by 10%, capping at a 60% redelegation fee.
1625
-
1626
- e.g: If 1000 mIO is redelegated and the fee rate is 10%, the fee will be 100 mIO. Resulting in 900 mIO being redelegated to the new gateway and 100 mIO being deducted back to the protocol balance.
1627
-
1628
- ```typescript
1629
- const io = IO.init({ signer: new ArweaveSigner(jwk) });
1630
-
1631
- const { id: txId } = await io.redelegateStake({
1632
- target: 't4Xr0_J4Iurt7caNST02cMotaz2FIbWQ4Kbj616RHl3',
1633
- source: 'HwFceQaMQnOBgKDpnFqCqgwKwEU5LBme1oXRuQOWSRA',
1634
- stakeQty: new IOToken(1000).toMIO(),
1635
- vaultId: 'fDrr0_J4Iurt7caNST02cMotaz2FIbWQ4Kcj616RHl3',
1636
- });
1637
- ```
1638
-
1639
- #### `getRedelegationFee({ address })`
1640
-
1641
- Retrieves the fee rate as percentage required to redelegate the stake of a specific address. Fee rate ranges from 0% to 60% based on the number of redelegations since the last fee reset.
1642
-
1643
- ```typescript
1644
- const io = IO.init();
1645
-
1646
- const fee = await io.getRedelegationFee({
1647
- address: 't4Xr0_J4Iurt7caNST02cMotaz2FIbWQ4Kbj616RHl3',
1648
- });
1649
- ```
1650
-
1651
- <details>
1652
- <summary>Output</summary>
1653
-
1654
- ```json
1655
- {
1656
- "redelegationFeeRate": 10,
1657
- "feeResetTimestamp": 1730996691117
1658
- }
1659
- ```
1660
-
1661
- </details>
1662
-
1663
1680
  ### Configuration
1664
1681
 
1665
1682
  The IO client class exposes APIs relevant to the ar.io process. It can be configured to use any AO Process ID that adheres to the [IO Network Spec]. By default, it will use the current [IO Testnet Process]. Refer to [AO Connect] for more information on how to configure an IO process to use specific AO infrastructure.