Merge pull request #363 from ar-io/alpha

chore: release 3.4.0
ar-io · Jan 31, 2025 · ab495a8 · ab495a8
2 parents a5317e4 + c987624
commit ab495a8
Show file tree

Hide file tree

Showing 16 changed files with 974 additions and 269 deletions.
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -10,36 +10,6 @@
 * **lua:** update lua code id ([76822a2](https://github.com/ar-io/ar-io-sdk/commit/76822a2b4b12df7449d6a0d4c25927d491a17faf))
 * **tags:** remove extra tags from spawn util ([f308b84](https://github.com/ar-io/ar-io-sdk/commit/f308b84cb48f7ecb4bd89d5dbc910002bd147dcc))
 
-## [3.3.1-alpha.4](https://github.com/ar-io/ar-io-sdk/compare/v3.3.1-alpha.3...v3.3.1-alpha.4) (2025-01-29)
-
-
-### Bug Fixes
-
-* **ant:** update ANT ids ([9f37e76](https://github.com/ar-io/ar-io-sdk/commit/9f37e768b43ad6fb6d813de1eba7eefe072bfb97))
-
-## [3.3.1-alpha.3](https://github.com/ar-io/ar-io-sdk/compare/v3.3.1-alpha.2...v3.3.1-alpha.3) (2025-01-28)
-
-
-### Bug Fixes
-
-* **ant:** bumps ids ([8eb2e38](https://github.com/ar-io/ar-io-sdk/commit/8eb2e388fe15e18b049c735ab414b750b7aa439b))
-
-## [3.3.1-alpha.2](https://github.com/ar-io/ar-io-sdk/compare/v3.3.1-alpha.1...v3.3.1-alpha.2) (2025-01-26)
-
-
-### Bug Fixes
-
-* **boot:** add boot loader logic to ant spawn util ([f00ab47](https://github.com/ar-io/ar-io-sdk/commit/f00ab47848979b05634677ad458940b033e9f90a))
-* **lua:** update lua code id ([76822a2](https://github.com/ar-io/ar-io-sdk/commit/76822a2b4b12df7449d6a0d4c25927d491a17faf))
-* **tags:** remove extra tags from spawn util ([f308b84](https://github.com/ar-io/ar-io-sdk/commit/f308b84cb48f7ecb4bd89d5dbc910002bd147dcc))
-
-## [3.3.1-alpha.1](https://github.com/ar-io/ar-io-sdk/compare/v3.3.0...v3.3.1-alpha.1) (2025-01-24)
-
-
-### Bug Fixes
-
-* **ants:** module bump _wSmbjfSlX3dZNcqE8JqKmj-DKum9uQ_jB08LwOKCyw ([8d442e0](https://github.com/ar-io/ar-io-sdk/commit/8d442e0c6fe102a8890b4b38d4b37c434004842d))
-
 # [3.3.0](https://github.com/ar-io/ar-io-sdk/compare/v3.2.0...v3.3.0) (2025-01-24)
 
 

diff --git a/CLI.md b/CLI.md
@@ -123,6 +123,11 @@ Commands:
   get-gateway-vaults [options]            Get the vaults of a gateway
   list-all-gateway-vaults [options]       List vaults from all gateways
   transfer [options]                      Transfer ARIO to another address
+  vaulted-transfer [options]              Transfer ARIO to another address into a locked vault
+  revoke-vault [options]                  Revoke a vaulted transfer as the controller
+  create-vault [options]                  Create a locked vault with balance from the sender
+  extend-vault [options]                  Extend the lock length of a vault as the recipient
+  increase-vault [options]                Increase the balance of a locked vault as the recipient
   join-network [options]                  Join a gateway to the AR.IO network
   leave-network [options]                 Leave a gateway from the AR.IO network
   update-gateway-settings [options]       Update AR.IO gateway settings
@@ -153,7 +158,9 @@ Commands:
   transfer-ant-ownership [options]        Transfer ownership of an ANT process
   add-ant-controller [options]            Add a controller to an ANT process
   remove-ant-controller [options]         Remove a controller from an ANT process
-  set-ant-record [options]                Set a record of an ANT process
+  set-ant-record [options]                Set a record of an ANT process. Deprecated: use set-ant-base-name and set-ant-undername
+  set-ant-base-name [options]             Set the base name of an ANT process
+  set-ant-undername [options]             Set an undername of an ANT process
   remove-ant-record [options]             Remove a record from an ANT process
   set-ant-ticker [options]                Set the ticker of an ANT process
   set-ant-name [options]                  Set the name of an ANT process

diff --git a/README.md b/README.md
@@ -33,6 +33,11 @@ This is the home of [ar.io] SDK. This SDK provides functionality for interacting
   - [Vaults](#vaults)
     - [`getVault({ address, vaultId })`](#getvault-address-vaultid-)
     - [`getVaults({ cursor, limit, sortBy, sortOrder })`](#getvaults-cursor-limit-sortby-sortorder-)
+    - [`vaultedTransfer({ recipient, quantity, lockLengthMs, revokable })`](#vaultedtransfer-recipient-quantity-locklengthms-revokable-)
+    - [`revokeVault({ recipient, vaultId })`](#revokevault-recipient-vaultid-)
+    - [`createVault({ lockLengthMs, quantity })`](#createvault-locklengthms-quantity-)
+    - [`extendVault({ vaultId, extendLengthMs })`](#extendvault-vaultid-extendlengthms-)
+    - [`increaseVault({ vaultId, quantity })`](#increasevault-vaultid-quantity-)
   - [Gateways](#gateways)
     - [`getGateway({ address })`](#getgateway-address-)
     - [`getGateways({ cursor, limit, sortBy, sortOrder })`](#getgateways-cursor-limit-sortby-sortorder-)
@@ -89,6 +94,9 @@ This is the home of [ar.io] SDK. This SDK provides functionality for interacting
     - [`transfer({ target })`](#transfer-target-)
     - [`setController({ controller })`](#setcontroller-controller-)
     - [`removeController({ controller })`](#removecontroller-controller-)
+    - [`setBaseNameRecord({ transactionId, ttlSeconds })`](#setbasenamerecord-transactionid-ttlseconds-)
+    - [`setUndernameRecord({ undername, transactionId, ttlSeconds })`](#setundernamerecord-undername-transactionid-ttlseconds-)
+    - [`removeUndernameRecord({ undername })`](#removeundernamerecord-undername-)
     - [`setRecord({ undername, transactionId, ttlSeconds })`](#setrecord-undername-transactionid-ttlseconds-)
     - [`removeRecord({ undername })`](#removerecord-undername-)
     - [`setName({ name })`](#setname-name-)
@@ -511,6 +519,79 @@ const vaults = await ario.getVaults({
 
 </details>
 
+#### `vaultedTransfer({ recipient, quantity, lockLengthMs, revokable })`
+
+Transfers `mARIO` to the designated `recipient` address and locks the balance for the specified `lockLengthMs` milliseconds. The `revokable` flag determines if the vaulted transfer can be revoked by the sender.
+
+_Note: Requires `signer` to be provided on `ARIO.init` to sign the transaction._
+
+```typescript
+const ario = ARIO.init({ signer: new ArweaveSigner(jwk) });
+const { id: txId } = await ario.vaultedTransfer(
+  {
+    recipient: '-5dV7nk7waR8v4STuwPnTck1zFVkQqJh5K9q9Zik4Y5',
+    quantity: new ARIOToken(1000).toMARIO(),
+    lockLengthMs: 1000 * 60 * 60 * 24 * 365, // 1 year
+    revokable: true,
+  },
+  // optional additional tags
+  { tags: [{ name: 'App-Name', value: 'My-Awesome-App' }] },
+);
+```
+
+#### `revokeVault({ recipient, vaultId })`
+
+Revokes a vaulted transfer by the recipient address and vault ID. Only the sender of the vaulted transfer can revoke it.
+
+_Note: Requires `signer` to be provided on `ARIO.init` to sign the transaction._
+
+```typescript
+const ario = ARIO.init({ signer: new ArweaveSigner(jwk) });
+const { id: txId } = await ario.revokeVault({
+  recipient: '-5dV7nk7waR8v4STuwPnTck1zFVkQqJh5K9q9Zik4Y5',
+  vaultId: 'IPdwa3Mb_9pDD8c2IaJx6aad51Ss-_TfStVwBuhtXMs',
+});
+```
+
+#### `createVault({ lockLengthMs, quantity })`
+
+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 { id: txId } = await ario.createVault({
+  lockLengthMs: 1000 * 60 * 60 * 24 * 365, // 1 year
+  quantity: new ARIOToken(1000).toMARIO(),
+});
+```
+
+#### `extendVault({ vaultId, extendLengthMs })`
+
+Extends the lock length of a signer's vault by the specified `extendLengthMs` milliseconds.
+
+```typescript
+const ario = ARIO.init({ signer: new ArweaveSigner(jwk) });
+
+const { id: txId } = await ario.extendVault({
+  vaultId: 'vaultIdOne',
+  extendLengthMs: 1000 * 60 * 60 * 24 * 365, // 1 year
+});
+```
+
+#### `increaseVault({ vaultId, quantity })`
+
+Increases the balance of a signer's vault by the specified `quantity` of mARIO.
+
+```typescript
+const ario = ARIO.init({ signer: new ArweaveSigner(jwk) });
+
+const { id: txId } = await ario.increaseVault({
+  vaultId: 'vaultIdOne',
+  quantity: new ARIOToken(1000).toMARIO(),
+});
+```
+
 ### Gateways
 
 #### `getGateway({ address })`
@@ -2024,9 +2105,70 @@ const { id: txId } = await ant.removeController(
 );
 ```
 
+#### `setBaseNameRecord({ transactionId, ttlSeconds })`
+
+Adds or updates the base name record for the ANT. This is the top level name of the ANT (e.g. ardrive.ar.io)
+
+_Note: Requires `signer` to be provided on `ANT.init` to sign the transaction._
+
+```typescript
+// get the ant for the base name
+const arnsRecord = await ario.getArNSRecord({ name: 'ardrive' });
+const ant = await ANT.init({ processId: arnsName.processId });
+const { id: txId } = await ant.setBaseNameRecord({
+  transactionId: '432l1cy0aksiL_x9M359faGzM_yjralacHIUo8_nQXM',
+  ttlSeconds: 3600,
+});
+
+// ardrive.ar.io will now resolve to the provided 432l1cy0aksiL_x9M359faGzM_yjralacHIUo8_nQXM transaction id
+```
+
+#### `setUndernameRecord({ undername, transactionId, ttlSeconds })`
+
+Adds or updates an undername record for the ANT. An undername is appended to the base name of the ANT (e.g. dapp_ardrive.ar.io)
+
+_Note: Requires `signer` to be provided on `ANT.init` to sign the transaction._
+
+> Records, or `undernames` are configured with the `transactionId` - the arweave transaction id the record resolves - and `ttlSeconds`, the Time To Live in the cache of client applications.
+
+```typescript
+const arnsRecord = await ario.getArNSRecord({ name: 'ardrive' });
+const ant = await ANT.init({ processId: arnsName.processId });
+const { id: txId } = await ant.setUndernameRecord(
+  {
+    undername: 'dapp',
+    transactionId: '432l1cy0aksiL_x9M359faGzM_yjralacHIUo8_nQXM',
+    ttlSeconds: 900,
+  },
+  // optional additional tags
+  { tags: [{ name: 'App-Name', value: 'My-Awesome-App' }] },
+);
+
+// dapp_ardrive.ar.io will now resolve to the provided 432l1cy0aksiL_x9M359faGzM_yjralacHIUo8_nQXM transaction id
+```
+
+#### `removeUndernameRecord({ undername })`
+
+Removes an undername record from the ANT process.
+
+_Note: Requires `signer` to be provided on `ANT.init` to sign the transaction._
+
+```typescript
+const { id: txId } = await ant.removeUndernameRecord(
+  { undername: 'dapp' },
+  // optional additional tags
+  { tags: [{ name: 'App-Name', value: 'My-Awesome-App' }] },
+);
+
+// dapp_ardrive.ar.io will no longer resolve to the provided transaction id
+```
+
 #### `setRecord({ undername, transactionId, ttlSeconds })`
 
-Updates or creates a record in the ANT process.
+> [!WARNING]
+> Deprecated: Use `setBaseNameRecord` or `setUndernameRecord` instead.
+
+Adds or updates a record for the ANT process. The `undername` parameter is used to specify the record name. Use `@` for the base name record.
 
 _Note: Requires `signer` to be provided on `ANT.init` to sign the transaction._
 
@@ -2046,16 +2188,23 @@ const { id: txId } = await ant.setRecord(
 
 #### `removeRecord({ undername })`
 
+> [!WARNING]
+> Deprecated: Use `removeUndernameRecord` instead.
+
 Removes a record from the ANT process.
 
 _Note: Requires `signer` to be provided on `ANT.init` to sign the transaction._
 
 ```typescript
+const arnsRecord = await ario.getArNSRecord({ name: 'ardrive' });
+const ant = await ANT.init({ processId: arnsName.processId });
 const { id: txId } = await ant.removeRecord(
-  { undername: 'remove-domemain' },
+  { undername: 'dapp' },
   // optional additional tags
   { tags: [{ name: 'App-Name', value: 'My-Awesome-App' }] },
 );
+
+// dapp_ardrive.ar.io will no longer resolve to the provided transaction id
 ```
 
 #### `setName({ name })`

diff --git a/package.json b/package.json
@@ -1,6 +1,6 @@
 {
   "name": "@ar.io/sdk",
-  "version": "3.3.1",
+  "version": "3.4.0-alpha.4",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/ar-io/ar-io-sdk.git"