@ar.io/sdk 3.21.0-alpha.1 → 3.21.1-alpha.1

package/README.md

@@ -2125,9 +2125,76 @@ ar.io spawn-ant --wallet-file wallet.json --module FKtQtOOtlcWCW2pXrwWFiCSlnuewM
 
 ### Versions
 
+#### `getModuleId({ graphqlUrl?, retries? })`
+
+Gets the module ID of the current ANT process by querying its spawn transaction tags. Results are cached after the first successful fetch.
+
+```typescript
+const moduleId = await ant.getModuleId();
+console.log(`ANT was spawned with module: ${moduleId}`);
+
+// With custom GraphQL URL and retries
+const moduleId = await ant.getModuleId({
+  graphqlUrl: 'https://arweave.net/graphql',
+  retries: 5
+});
+```
+
+<details>
+  <summary>Output</summary>
+
+```json
+"FKtQtOOtlcWCW2pXrwWFiCSlnuewMZOHCzhulVkyqBE"
+```
+
+</details>
+
+#### `getVersion({ antRegistryId?, graphqlUrl?, retries? })`
+
+Gets the version string of the current ANT by matching its module ID with versions from the ANT registry.
+
+```typescript
+const version = await ant.getVersion();
+console.log(`ANT is running version: ${version}`);
+
+// With custom ANT registry
+const version = await ant.getVersion({
+  antRegistryId: 'custom-ant-registry-id'
+});
+```
+
+<details>
+  <summary>Output</summary>
+
+```json
+"23"
+```
+
+</details>
+
+#### `isLatestVersion({ antRegistryId?, graphqlUrl?, retries? })`
+
+Checks if the current ANT version is the latest according to the ANT registry.
+
+```typescript
+const isLatest = await ant.isLatestVersion();
+if (!isLatest) {
+  console.log('ANT can be upgraded to the latest version');
+}
+```
+
+<details>
+  <summary>Output</summary>
+
+```json
+true
+```
+
+</details>
+
 #### `getANTVersions`
 
-Returns the full array of available ANT versions and the latest version from the ANT registry.
+Static method that returns the full array of available ANT versions and the latest version from the ANT registry.
 
 ```typescript
 import { ANT } from '@ar.io/sdk';
@@ -2155,12 +2222,17 @@ Result:
 
 #### `getLatestANTVersion()`
 
-Returns the latest ANT version from the ANT registry.
+Static method that returns the latest ANT version from the ANT registry.
 
 ```typescript
 import { ANT } from '@ar.io/sdk';
 
 // Get the latest ANT version
+import { ANT } from '@ar.io/sdk';
+
+// Get all available ANT versions
+const antVersions = ANT.versions;
+const versions = await antVersions.getANTVersions();
 const latestVersion = await antVersions.getLatestANTVersion();
 ```
 
@@ -2307,6 +2379,40 @@ const owner = await ant.getOwner();
 
 </details>
 
+#### `getName()`
+
+Returns the name of the ANT (not the same as ArNS name).
+
+```typescript
+const name = await ant.getName();
+```
+
+<details>
+  <summary>Output</summary>
+
+```json
+"ArDrive"
+```
+
+</details>
+
+#### `getTicker()`
+
+Returns the ticker symbol of the ANT.
+
+```typescript
+const ticker = await ant.getTicker();
+```
+
+<details>
+  <summary>Output</summary>
+
+```json
+"ANT-ARDRIVE"
+```
+
+</details>
+
 #### `getControllers()`
 
 Returns the controllers of the configured ANT process.
@@ -2363,6 +2469,72 @@ const records = await ant.getRecords();
 
 </details>
 
+#### `getRecord({ undername })`
+
+Returns a specific record by its undername.
+
+```typescript
+const record = await ant.getRecord({ undername: 'dapp' });
+```
+
+<details>
+  <summary>Output</summary>
+
+```json
+{
+  "transactionId": "432l1cy0aksiL_x9M359faGzM_yjralacHIUo8_nQXM",
+  "ttlSeconds": 900,
+  "owner": "alice-wallet-address-123...",
+  "displayName": "Alice's Site",
+  "logo": "avatar-tx-id-456...",
+  "description": "Personal portfolio and blog",
+  "keywords": ["portfolio", "personal", "blog"]
+}
+```
+
+</details>
+
+### Balances
+
+#### `getBalances()`
+
+Returns all token balances for the ANT.
+
+```typescript
+const balances = await ant.getBalances();
+```
+
+<details>
+  <summary>Output</summary>
+
+```json
+{
+  "ccp3blG__gKUvG3hsGC2u06aDmqv4CuhuDJGOIg0jw4": 1,
+  "aGzM_yjralacHIUo8_nQXMbh9l1cy0aksiL_x9M359f": 0
+}
+```
+
+</details>
+
+#### `getBalance({ address })`
+
+Returns the balance of a specific address.
+
+```typescript
+const balance = await ant.getBalance({
+  address: 'ccp3blG__gKUvG3hsGC2u06aDmqv4CuhuDJGOIg0jw4',
+});
+```
+
+<details>
+  <summary>Output</summary>
+
+```json
+1
+```
+
+</details>
+
 ### Transfer
 
 #### `transfer({ target })`
@@ -2381,14 +2553,14 @@ const { id: txId } = await ant.transfer(
 
 ### Controllers
 
-#### `setController({ controller })`
+#### `addController({ controller })`
 
 Adds a new controller to the list of approved controllers on the ANT. Controllers can set records and change the ticker and name of the ANT process.
 
 _Note: Requires `signer` to be provided on `ANT.init` to sign the transaction._
 
 ```typescript
-const { id: txId } = await ant.setController(
+const { id: txId } = await ant.addController(
   { controller: 'aGzM_yjralacHIUo8_nQXMbh9l1cy0aksiL_x9M359f' },
   // optional additional tags
   { tags: [{ name: 'App-Name', value: 'My-Awesome-App' }] },
@@ -2595,7 +2767,7 @@ Sets the keywords of the ANT process.
 _Note: Requires `signer` to be provided on `ANT.init` to sign the transaction._
 
 ```typescript
-const { id: txId } = await ant.setDescription(
+const { id: txId } = await ant.setKeywords(
   { keywords: ['Game', 'FPS', 'AO'] },
   // optional tags
   { tags: [{ name: 'App-Name', value: 'My-Awesome-App' }] },
@@ -2841,13 +3013,60 @@ const recordAfter = await ant.getRecord({ undername: 'alice' });
 console.log(recordAfter.owner); // undefined (controlled by ANT owner again)
 ```
 
+### Static Methods
+
+#### `ANT.fork({ signer, antProcessId, module?, scheduler?, state?, ao?, antRegistryId?, onSigningProgress? })`
+
+Forks an existing ANT process to create a new one with the same state but potentially a different module. This is used for upgrading ANTs to new versions.
+
+```typescript
+const newProcessId = await ANT.fork({
+  signer: new ArweaveSigner(jwk),
+  antProcessId: 'existing-ant-process-id',
+  // Optional: specify a specific module ID, defaults to latest from registry
+  module: 'new-module-id',
+  onSigningProgress: (event, payload) => {
+    console.log(`Fork progress: ${event}`);
+  },
+});
+
+console.log(`Forked ANT to new process: ${newProcessId}`);
+```
+
+#### `ANT.upgrade({ signer, antProcessId, reassignAffiliatedNames?, names?, arioProcessId?, antRegistryId?, ao?, logger?, skipVersionCheck?, onSigningProgress?, hyperbeamUrl? })`
+
+Static method to upgrade an ANT by forking it to the latest version and reassigning names.
+
+```typescript
+// Upgrade and reassign all affiliated names
+const result = await ANT.upgrade({
+  signer: new ArweaveSigner(jwk),
+  antProcessId: 'existing-ant-process-id',
+  reassignAffiliatedNames: true,
+  arioProcessId: ARIO_MAINNET_PROCESS_ID
+});
+
+// Upgrade and reassign specific names
+const result = await ANT.upgrade({
+  signer: new ArweaveSigner(jwk),
+  antProcessId: 'existing-ant-process-id',
+  names: ['ardrive', 'example'],
+  reassignAffiliatedNames: false,
+  arioProcessId: ARIO_MAINNET_PROCESS_ID
+});
+
+console.log(`Upgraded to process: ${result.forkedProcessId}`);
+console.log(`Successfully reassigned names: ${Object.keys(result.reassignedNames)}`);
+console.log(`Failed reassignments: ${Object.keys(result.failedReassignedNames)}`);
+```
+
 ## Token Conversion
 
 The ARIO process stores all values as mARIO (milli-ARIO) to avoid floating-point arithmetic issues. The SDK provides an `ARIOToken` and `mARIOToken` classes to handle the conversion between ARIO and mARIO, along with rounding logic for precision.
 
 **All process interactions expect values in mARIO. If numbers are provided as inputs, they are assumed to be in raw mARIO values.**
 
-### Converting ARIO to mARIO
+#### Converting ARIO to mARIO
 
 ```typescript
 import { ARIOToken, mARIOToken } from '@ar.io/sdk';
@@ -2863,7 +3082,7 @@ const arioValue = new mARIOToken(mARIOValue).toARIO();
 
 The library uses a lightweight console logger by default for both Node.js and web environments. The logger outputs structured JSON logs with timestamps. You can configure the log level via `setLogLevel()` API or provide a custom logger that satisfies the `ILogger` interface.
 
-### Default Console Logger
+#### Default Logger
 
 ```typescript
 import { Logger } from '@ar.io/sdk';
@@ -2875,7 +3094,7 @@ Logger.default.setLogLevel('debug');
 const logger = new Logger({ level: 'debug' });
 ```
 
-### Custom Logger Implementation
+#### Custom Logger Implementation
 
 You can provide any custom logger that implements the `ILogger` interface:
 
@@ -2894,15 +3113,18 @@ const customLogger: ILogger = {
 };
 
 // Use custom logger with any class
-const ario = new ARIO({ logger: customLogger });
+const ario = ARIO.mainnet({ logger: customLogger });
+
+// or set it as the default logger in the entire SDK
+Logger.default = customLogger;
 ```
 
-### Winston Logger (Optional)
+#### Winston Logger (Optional)
 
 For advanced logging features, you can optionally install Winston and use the provided Winston logger adapter:
 
 ```bash
-npm install winston
+yarn add winston
 ```
 
 ```typescript
@@ -2914,10 +3136,13 @@ const winstonLogger = new WinstonLogger({
 });
 
 // Use with any class that accepts a logger
-const ario = new ARIO({ logger: winstonLogger });
+const ario = ARIO.mainnet({ logger: winstonLogger });
+
+// or set it as the default logger in the entire SDK
+Logger.default = winstonLogger;
 ```
 
-### Other Popular Loggers
+#### Other Popular Loggers
 
 You can easily integrate other popular logging libraries:
 
@@ -2935,12 +3160,15 @@ const adapter: ILogger = {
   setLogLevel: (level) => bunyanLogger.level(level),
 };
 
-const ario = new ARIO({ logger: adapter });
+const ario = ARIO.mainnet({ logger: adapter });
+
+// or set it as the default logger in the entire SDK
+Logger.default = adapter;
 ```
 
 ## Pagination
 
-### Overview
+#### Overview
 
 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-).
 
@@ -2967,7 +3195,7 @@ while (hasMore) {
 }
 ```
 
-### Filtering
+#### Filtering
 
 Paginated APIs also support filtering by providing a `filters` parameter. Filters can be applied to any field in the response. When multiple keys are provided, they are treated as AND conditions (all conditions must match). When multiple values are provided for a single key (as an array), they are treated as OR conditions (any value can match).