@ar.io/sdk 3.8.0 → 3.8.2-alpha.1

package/README.md

@@ -13,6 +13,7 @@ This is the home of [ar.io] SDK. This SDK provides functionality for interacting
 - [Installation](#installation)
 - [Quick Start](#quick-start)
 - [Usage](#usage)
+  - [Networks (Mainnet, Testnet, etc.)](#networks-mainnet-testnet-etc)
   - [Web](#web)
     - [Bundlers (Webpack, Rollup, ESbuild, etc.)](#bundlers-webpack-rollup-esbuild-etc)
     - [Browser](#browser)
@@ -152,7 +153,7 @@ yarn add @ar.io/sdk --ignore-engines
 ```typescript
 import { ARIO } from '@ar.io/sdk';
 
-const ario = ARIO.init();
+const ario = ARIO.init(); // defaults to mainnet
 const gateways = await ario.getGateways();
 ```
 
@@ -208,6 +209,29 @@ const gateways = await ario.getGateways();
 
 The SDK is provided in both CommonJS and ESM formats and is compatible with bundlers such as Webpack, Rollup, and ESbuild. Utilize the appropriately named exports provided by this SDK's [package.json] based on your project's configuration. Refer to the [examples] directory to see how to use the SDK in various environments.
 
+### Networks (Mainnet, Testnet, etc.)
+
+The SDK provides the following process IDs for the mainnet and testnet environments:
+
+- `ARIO_MAINNET_PROCESS_ID` - Mainnet ARIO process ID (production)
+- `ARIO_TESTNET_PROCESS_ID` - Testnet ARIO process ID (testing and development)
+- `ARIO_DEVNET_PROCESS_ID` - Devnet ARIO process ID (for development purposes)
+
+As of `v3.8.1` the SDK defaults all API interactions to **mainnet**. To use the **testnet** or **devnet** provide the appropriate `ARIO_TESTNET_PROCESS_ID` or `ARIO_DEVNET_PROCESS_ID` when initializing the client.
+
+```typescript
+import {
+  ARIO,
+  ARIO_DEVNET_PROCESS_ID,
+  ARIO_MAINNET_PROCESS_ID,
+  ARIO_TESTNET_PROCESS_ID,
+} from '@ar.io/sdk';
+```
+
+```typescript
+const ario = ARIO.init({ processId: ARIO_TESTNET_PROCESS_ID }); // use the testnet contract
+```
+
 ### Web
 
 #### Bundlers (Webpack, Rollup, ESbuild, etc.)
@@ -296,7 +320,7 @@ Factory function to that creates a read-only or writeable client. By providing a
 
 ```typescript
 // read-only client
-const ario = ARIO.init()
+const ario = ARIO.init();
 
 // read-write client for browser environments
 const ario = ARIO.init({ signer: new ArConnectSigner(window.arweaveWallet, Arweave.init({}))});
@@ -436,7 +460,10 @@ Transfers `mARIO` to the designated `target` recipient address. Requires `signer
 _Note: Requires `signer` to be provided on `ARIO.init` to sign the transaction._
 
 ```typescript
-const ario = ARIO.init({ signer: new ArweaveSigner(jwk) });
+const ario = ARIO.init({
+  processId: ARIO_MAINNET_PROCESS_ID,
+  signer: new ArweaveSigner(jwk),
+});
 const { id: txId } = await ario.transfer(
   {
     target: '-5dV7nk7waR8v4STuwPnTck1zFVkQqJh5K9q9Zik4Y5',
@@ -547,7 +574,10 @@ Revokes a vaulted transfer by the recipient address and vault ID. Only the sende
 _Note: Requires `signer` to be provided on `ARIO.init` to sign the transaction._
 
 ```typescript
-const ario = ARIO.init({ signer: new ArweaveSigner(jwk) });
+const ario = ARIO.init({
+  processId: ARIO_MAINNET_PROCESS_ID,
+  signer: new ArweaveSigner(jwk),
+});
 const { id: txId } = await ario.revokeVault({
   recipient: '-5dV7nk7waR8v4STuwPnTck1zFVkQqJh5K9q9Zik4Y5',
   vaultId: 'IPdwa3Mb_9pDD8c2IaJx6aad51Ss-_TfStVwBuhtXMs',
@@ -559,7 +589,10 @@ const { id: txId } = await ario.revokeVault({
 Creates a vault for the specified `quantity` of mARIO from the signer's balance and locks it for the specified `lockLengthMs` milliseconds.
 
 ```typescript
-const ario = ARIO.init({ signer: new ArweaveSigner(jwk) });
+const ario = ARIO.init({
+  processId: ARIO_MAINNET_PROCESS_ID,
+  signer: new ArweaveSigner(jwk),
+});
 
 const { id: txId } = await ario.createVault({
   lockLengthMs: 1000 * 60 * 60 * 24 * 365, // 1 year
@@ -572,7 +605,10 @@ const { id: txId } = await ario.createVault({
 Extends the lock length of a signer's vault by the specified `extendLengthMs` milliseconds.
 
 ```typescript
-const ario = ARIO.init({ signer: new ArweaveSigner(jwk) });
+const ario = ARIO.init({
+  processId: ARIO_MAINNET_PROCESS_ID,
+  signer: new ArweaveSigner(jwk),
+});
 
 const { id: txId } = await ario.extendVault({
   vaultId: 'vaultIdOne',
@@ -585,7 +621,10 @@ const { id: txId } = await ario.extendVault({
 Increases the balance of a signer's vault by the specified `quantity` of mARIO.
 
 ```typescript
-const ario = ARIO.init({ signer: new ArweaveSigner(jwk) });
+const ario = ARIO.init({
+  processId: ARIO_MAINNET_PROCESS_ID,
+  signer: new ArweaveSigner(jwk),
+});
 
 const { id: txId } = await ario.increaseVault({
   vaultId: 'vaultIdOne',
@@ -761,7 +800,10 @@ Joins a gateway to the ar.io network via its associated wallet.
 _Note: Requires `signer` to be provided on `ARIO.init` to sign the transaction._
 
 ```typescript
-const ario = ARIO.init({ signer: new ArweaveSigner(jwk) });
+const ario = ARIO.init({
+  processId: ARIO_MAINNET_PROCESS_ID,
+  signer: new ArweaveSigner(jwk),
+});
 const { id: txId } = await ario.joinNetwork(
   {
     qty: new ARIOToken(10_000).toMARIO(), // minimum operator stake allowed
@@ -789,7 +831,10 @@ Sets the gateway as `leaving` on the ar.io network. Requires `signer` to be prov
 _Note: Requires `signer` to be provided on `ARIO.init` to sign the transaction._
 
 ```typescript
-const ario = ARIO.init({ signer: new ArweaveSigner(jwk) });
+const ario = ARIO.init({
+  processId: ARIO_MAINNET_PROCESS_ID,
+  signer: new ArweaveSigner(jwk),
+});
 
 const { id: txId } = await ario.leaveNetwork(
   // optional additional tags
@@ -804,7 +849,10 @@ Writes new gateway settings to the callers gateway configuration.
 _Note: Requires `signer` to be provided on `ARIO.init` to sign the transaction._
 
 ```typescript
-const ario = ARIO.init({ signer: new ArweaveSigner(jwk) });
+const ario = ARIO.init({
+  processId: ARIO_MAINNET_PROCESS_ID,
+  signer: new ArweaveSigner(jwk),
+});
 const { id: txId } = await ario.updateGatewaySettings(
   {
     // any other settings you want to update
@@ -822,7 +870,10 @@ Increases the callers stake on the target gateway.
 _Note: Requires `signer` to be provided on `ARIO.init` to sign the transaction._
 
 ```typescript
-const ario = ARIO.init({ signer: new ArweaveSigner(jwk) });
+const ario = ARIO.init({
+  processId: ARIO_MAINNET_PROCESS_ID,
+  signer: new ArweaveSigner(jwk),
+});
 const { id: txId } = await ario.increaseDelegateStake(
   {
     target: 't4Xr0_J4Iurt7caNST02cMotaz2FIbWQ4Kbj616RHl3',
@@ -840,7 +891,10 @@ Decreases the callers stake on the target gateway. Can instantly decrease stake
 _Note: Requires `signer` to be provided on `ARIO.init` to sign the transaction._
 
 ```typescript
-const ario = ARIO.init({ signer: new ArweaveSigner(jwk) });
+const ario = ARIO.init({
+  processId: ARIO_MAINNET_PROCESS_ID,
+  signer: new ArweaveSigner(jwk),
+});
 const { id: txId } = await ario.decreaseDelegateStake(
   {
     target: 't4Xr0_J4Iurt7caNST02cMotaz2FIbWQ4Kbj616RHl3',
@@ -855,7 +909,10 @@ const { id: txId } = await ario.decreaseDelegateStake(
 Pay the early withdrawal fee and withdraw instantly.
 
 ```typescript
-const ario = ARIO.init({ signer: new ArweaveSigner(jwk) });
+const ario = ARIO.init({
+  processId: ARIO_MAINNET_PROCESS_ID,
+  signer: new ArweaveSigner(jwk),
+});
 const { id: txId } = await ario.decreaseDelegateStake({
   target: 't4Xr0_J4Iurt7caNST02cMotaz2FIbWQ4Kbj616RHl3',
   qty: new ARIOToken(100).toMARIO(),
@@ -1081,7 +1138,10 @@ Increases the callers operator stake. Must be executed with a wallet registered
 _Note: Requires `signer` to be provided on `ARIO.init` to sign the transaction._
 
 ```typescript
-const ario = ARIO.init({ signer: new ArweaveSigner(jwk) });
+const ario = ARIO.init({
+  processId: ARIO_MAINNET_PROCESS_ID,
+  signer: new ArweaveSigner(jwk),
+});
 const { id: txId } = await ario.increaseOperatorStake(
   {
     qty: new ARIOToken(100).toMARIO(),
@@ -1099,7 +1159,10 @@ Decreases the callers operator stake. Must be executed with a wallet registered
 _Note: Requires `signer` to be provided on `ARIO.init` to sign the transaction._
 
 ```typescript
-const ario = ARIO.init({ signer: new ArweaveSigner(jwk) });
+const ario = ARIO.init({
+  processId: ARIO_MAINNET_PROCESS_ID,
+  signer: new ArweaveSigner(jwk),
+});
 const { id: txId } = await ario.decreaseOperatorStake(
   {
     qty: new ARIOToken(100).toMARIO(),
@@ -1117,7 +1180,10 @@ Redelegates the stake of a specific address to a new gateway. Vault ID may be op
 e.g: If 1000 mARIO is redelegated and the fee rate is 10%, the fee will be 100 mARIO. Resulting in 900 mARIO being redelegated to the new gateway and 100 mARIO being deducted back to the protocol balance.
 
 ```typescript
-const ario = ARIO.init({ signer: new ArweaveSigner(jwk) });
+const ario = ARIO.init({
+  processId: ARIO_MAINNET_PROCESS_ID,
+  signer: new ArweaveSigner(jwk),
+});
 
 const { id: txId } = await ario.redelegateStake({
   target: 't4Xr0_J4Iurt7caNST02cMotaz2FIbWQ4Kbj616RHl3',
@@ -1327,7 +1393,10 @@ Increases the undername support of a domain up to a maximum of 10k. Domains, by
 _Note: Requires `signer` to be provided on `ARIO.init` to sign the transaction._
 
 ```typescript
-const ario = ARIO.init({ signer: new ArweaveSigner(jwk) });
+const ario = ARIO.init({
+  processId: ARIO_MAINNET_PROCESS_ID,
+  signer: new ArweaveSigner(jwk),
+});
 const { id: txId } = await ario.increaseUndernameLimit(
   {
     name: 'ar-io',
@@ -1343,7 +1412,10 @@ const { id: txId } = await ario.increaseUndernameLimit(
 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.
 
 ```typescript
-const ario = ARIO.init({ signer: new ArweaveSigner(jwk) });
+const ario = ARIO.init({
+  processId: ARIO_MAINNET_PROCESS_ID,
+  signer: new ArweaveSigner(jwk),
+});
 const { id: txId } = await ario.extendLease(
   {
     name: 'ar-io',
@@ -1888,6 +1960,9 @@ const request = await ario.getPrimaryNameRequest({
 The ARIO client class exposes APIs relevant to the ar.io process. It can be configured to use any AO Process ID that adheres to the [ARIO Network Spec]. By default, it will use the current [ARIO Testnet Process]. Refer to [AO Connect] for more information on how to configure an ARIO process to use specific AO infrastructure.
 
 ```typescript
+import { ARIO } from '@ar.io/sdk';
+import { connect } from '@permaweb/aoconnect';
+
 // provide a custom ao infrastructure and process id
 const ario = ARIO.init({
   process: new AoProcess({
@@ -2327,7 +2402,7 @@ _Note: Requires `signer` to be provided on `ANT.init` to sign the transaction._
 ```typescript
 const { id: txId } = await ant.releaseName({
   name: 'permalink',
-  arioProcessId: ARIO_TESTNET_PROCESS_ID, // releases the name owned by the ANT and sends it to recently returned names on the ARIO contract
+  arioProcessId: ARIO_MAINNET_PROCESS_ID, // releases the name owned by the ANT and sends it to recently returned names on the ARIO contract
 });
 ```
 
@@ -2340,7 +2415,7 @@ _Note: Requires `signer` to be provided on `ANT.init` to sign the transaction._
 ```typescript
 const { id: txId } = await ant.reassignName({
   name: 'ardrive',
-  arioProcessId: ARIO_TESTNET_PROCESS_ID,
+  arioProcessId: ARIO_MAINNET_PROCESS_ID,
   antProcessId: NEW_ANT_PROCESS_ID, // the new ANT process id that will take over ownership of the name
 });
 ```
@@ -2355,7 +2430,7 @@ _Note: Requires `signer` to be provided on `ANT.init` to sign the transaction._
 const { id: txId } = await ant.approvePrimaryNameRequest({
   name: 'arns',
   address: 't4Xr0_J4Iurt7caNST02cMotaz2FIbWQ4Kbj616RHl3', // must match the request initiator address
-  arioProcessId: ARIO_TESTNET_PROCESS_ID, // the ARIO process id to use for the request
+  arioProcessId: ARIO_MAINNET_PROCESS_ID, // the ARIO process id to use for the request
 });
 ```
 
@@ -2368,7 +2443,7 @@ _Note: Requires `signer` to be provided on `ANT.init` to sign the transaction._
 ```typescript
 const { id: txId } = await ant.removePrimaryNames({
   names: ['arns', 'test_arns'], // any primary names associated with a base name controlled by this ANT will be removed
-  arioProcessId: ARIO_TESTNET_PROCESS_ID,
+  arioProcessId: ARIO_MAINNET_PROCESS_ID,
   notifyOwners: true, // if true, the owners of the removed names will be send AO messages to notify them of the removal
 });
 ```