feat(vault apis): init write methods+commands for create/extend/incre…

…ase vault PE-7541

src/cli/cli.ts

@@ -69,6 +69,9 @@ import {
   listGateways,
 } from './commands/readCommands.js';
 import {
+  createVaultCLICommand,
+  extendVaultCLICommand,
+  increaseVaultCLICommand,
   revokeVaultCLICommand,
   transferCLICommand,
   vaultedTransferCLICommand,
@@ -452,6 +455,27 @@ makeCommand({
   action: revokeVaultCLICommand,
 });
 
+makeCommand({
+  name: 'create-vault',
+  description: 'Create a locked vault with balance from the sender',
+  options: [...writeActionOptions, optionMap.lockLengthMs, optionMap.quantity],
+  action: createVaultCLICommand,
+});
+
+makeCommand({
+  name: 'extend-vault',
+  description: 'Extend the lock length of a vault as the recipient',
+  options: [...writeActionOptions, optionMap.vaultId, optionMap.extendLengthMs],
+  action: extendVaultCLICommand,
+});
+
+makeCommand({
+  name: 'increase-vault',
+  description: 'Increase the balance of a locked vault as the recipient',
+  options: [...writeActionOptions, optionMap.vaultId, optionMap.quantity],
+  action: increaseVaultCLICommand,
+});
+
 makeCommand({
   name: 'join-network',
   description: 'Join a gateway to the AR.IO network',

src/cli/commands/transfer.ts

@@ -14,6 +14,9 @@
  * limitations under the License.
  */
 import {
+  AoCreateVaultParams,
+  AoExtendVaultParams,
+  AoIncreaseVaultParams,
   AoRevokeVaultParams,
   AoVaultedTransferParams,
 } from '../../types/io.js';
@@ -153,3 +156,125 @@ export async function revokeVaultCLICommand(
 
   return output;
 }
+
+export async function createVaultCLICommand(
+  o: CLIWriteOptionsFromAoParams<AoCreateVaultParams>,
+): Promise<JsonSerializable> {
+  const mARIOQuantity = requiredMARIOFromOptions(o, 'quantity');
+  const { ario, signerAddress } = writeARIOFromOptions(o);
+  const lockLengthMs = requiredPositiveIntegerFromOptions(o, 'lockLengthMs');
+
+  if (!o.skipConfirmation) {
+    await assertEnoughMARIOBalance({
+      ario,
+      address: signerAddress,
+      mARIOQuantity,
+    });
+
+    const confirm = await confirmationPrompt(
+      `Are you sure you want to create a vault with ${formatMARIOToARIOWithCommas(mARIOQuantity)} ARIO, locked for ${lockLengthMs}ms?`,
+    );
+    if (!confirm) {
+      return { message: 'Vault creation aborted by user' };
+    }
+  }
+
+  const result = await ario.createVault(
+    {
+      quantity: mARIOQuantity,
+      lockLengthMs,
+    },
+    writeActionTagsFromOptions(o),
+  );
+
+  const output = {
+    senderAddress: signerAddress,
+    transferResult: result,
+    message: `Successfully created vault with ${formatMARIOToARIOWithCommas(mARIOQuantity)} ARIO`,
+  };
+
+  return output;
+}
+
+export async function extendVaultCLICommand(
+  o: CLIWriteOptionsFromAoParams<AoExtendVaultParams>,
+) {
+  const { ario, signerAddress } = writeARIOFromOptions(o);
+  const vaultId = requiredStringFromOptions(o, 'vaultId');
+  const extendLengthMs = requiredPositiveIntegerFromOptions(
+    o,
+    'extendLengthMs',
+  );
+
+  if (!o.skipConfirmation) {
+    const vault = await ario.getVault({ vaultId, address: signerAddress });
+    if (!vault) {
+      throw new Error(
+        `Vault for signer '${signerAddress}' with vault id '${vaultId}' not found`,
+      );
+    }
+
+    const confirm = await confirmationPrompt(
+      `Are you sure you want to extend vault with id ${vaultId} for ${extendLengthMs}ms?`,
+    );
+    if (!confirm) {
+      return { message: 'Vault extension aborted by user' };
+    }
+  }
+
+  const result = await ario.extendVault(
+    {
+      vaultId,
+      extendLengthMs,
+    },
+    writeActionTagsFromOptions(o),
+  );
+
+  const output = {
+    senderAddress: signerAddress,
+    transferResult: result,
+    message: `Successfully extended vault with id ${vaultId}`,
+  };
+
+  return output;
+}
+
+export async function increaseVaultCLICommand(
+  o: CLIWriteOptionsFromAoParams<AoIncreaseVaultParams>,
+) {
+  const mARIOQuantity = requiredMARIOFromOptions(o, 'quantity');
+  const { ario, signerAddress } = writeARIOFromOptions(o);
+  const vaultId = requiredStringFromOptions(o, 'vaultId');
+
+  if (!o.skipConfirmation) {
+    const vault = await ario.getVault({ vaultId, address: signerAddress });
+    if (!vault) {
+      throw new Error(
+        `Vault for signer '${signerAddress}' with vault id '${vaultId}' not found`,
+      );
+    }
+
+    const confirm = await confirmationPrompt(
+      `Are you sure you want to increase vault with id ${vaultId} by ${formatMARIOToARIOWithCommas(mARIOQuantity)} ARIO?`,
+    );
+    if (!confirm) {
+      return { message: 'Vault increase aborted by user' };
+    }
+  }
+
+  const result = await ario.increaseVault(
+    {
+      vaultId,
+      quantity: mARIOQuantity,
+    },
+    writeActionTagsFromOptions(o),
+  );
+
+  const output = {
+    senderAddress: signerAddress,
+    transferResult: result,
+    message: `Successfully increased vault with id ${vaultId} by ${formatMARIOToARIOWithCommas(mARIOQuantity)} ARIO`,
+  };
+
+  return output;
+}

src/cli/options.ts

@@ -251,7 +251,11 @@ export const optionMap = {
   },
   lockLengthMs: {
     alias: '--lock-length-ms <lockLengthMs>',
-    description: 'The length of time in milliseconds to lock the transfer for',
+    description: 'The length of time in milliseconds to lock the vault for',
+  },
+  extendLengthMs: {
+    alias: '--extend-length-ms <extendLengthMs>',
+    description: 'The length of time in milliseconds to extend the vault for',
   },
   recipient: {
     alias: '--recipient <recipient>',

src/common/io.ts

@@ -50,16 +50,19 @@ import {
   AoArNSPurchaseParams,
   AoArNSReservedNameDataWithName,
   AoBuyRecordParams,
+  AoCreateVaultParams,
   AoDelegation,
   AoEpochData,
   AoEpochSettings,
   AoExtendLeaseParams,
+  AoExtendVaultParams,
   AoGateway,
   AoGatewayDelegateWithAddress,
   AoGatewayRegistrySettings,
   AoGatewayVault,
   AoGetCostDetailsParams,
   AoIncreaseUndernameLimitParams,
+  AoIncreaseVaultParams,
   AoPaginatedAddressParams,
   AoRegistrationFees,
   AoRevokeVaultParams,
@@ -812,6 +815,54 @@ export class ARIOWriteable extends ARIOReadable implements AoARIOWrite {
     });
   }
 
+  async createVault(
+    { lockLengthMs, quantity }: AoCreateVaultParams,
+    options?: WriteOptions,
+  ): Promise<AoMessageResult> {
+    const { tags = [] } = options || {};
+    return this.process.send({
+      tags: [
+        ...tags,
+        { name: 'Action', value: 'Create-Vault' },
+        { name: 'Lock-Length', value: lockLengthMs.toString() },
+        { name: 'Quantity', value: quantity.toString() },
+      ],
+      signer: this.signer,
+    });
+  }
+
+  async extendVault(
+    { vaultId, extendLengthMs }: AoExtendVaultParams,
+    options?: WriteOptions,
+  ): Promise<AoMessageResult> {
+    const { tags = [] } = options || {};
+    return this.process.send({
+      tags: [
+        ...tags,
+        { name: 'Action', value: 'Extend-Vault' },
+        { name: 'Vault-Id', value: vaultId },
+        { name: 'Extend-Length', value: extendLengthMs.toString() },
+      ],
+      signer: this.signer,
+    });
+  }
+
+  async increaseVault(
+    { vaultId, quantity }: AoIncreaseVaultParams,
+    options?: WriteOptions,
+  ): Promise<AoMessageResult> {
+    const { tags = [] } = options || {};
+    return this.process.send({
+      tags: [
+        ...tags,
+        { name: 'Action', value: 'Increase-Vault' },
+        { name: 'Vault-Id', value: vaultId },
+        { name: 'Quantity', value: quantity.toString() },
+      ],
+      signer: this.signer,
+    });
+  }
+
   async joinNetwork(
     {
       operatorStake,

src/types/ant.ts

@@ -16,7 +16,7 @@
 import { z } from 'zod';
 
 import { ARWEAVE_TX_REGEX } from '../constants.js';
-import { AoMessageResult, WalletAddress, WriteOptions } from './common.js';
+import { AoWriteAction, WalletAddress } from './common.js';
 
 /**
  * example error:
@@ -203,44 +203,38 @@ export interface AoANTRead {
 }
 
 export interface AoANTWrite extends AoANTRead {
-  transfer: WriteAction<{ target: WalletAddress }>;
-  addController: WriteAction<{ controller: WalletAddress }>;
-  removeController: WriteAction<{ controller: WalletAddress }>;
+  transfer: AoWriteAction<{ target: WalletAddress }>;
+  addController: AoWriteAction<{ controller: WalletAddress }>;
+  removeController: AoWriteAction<{ controller: WalletAddress }>;
   /** @deprecated Use setUndernameRecord instead for undernames, and setBaseNameRecord instead for the top level name (e.g. "@") */
-  setRecord: WriteAction<AoANTSetUndernameRecordParams>;
-  removeRecord: WriteAction<{ undername: string }>;
-  setBaseNameRecord: WriteAction<AoANTSetBaseNameRecordParams>;
-  setUndernameRecord: WriteAction<AoANTSetUndernameRecordParams>;
-  removeUndernameRecord: WriteAction<{ undername: string }>;
-  setTicker: WriteAction<{ ticker: string }>;
-  setDescription: WriteAction<{ description: string }>;
-  setKeywords: WriteAction<{ keywords: string[] }>;
-  setName: WriteAction<{ name: string }>;
-  setLogo: WriteAction<{ txId: string }>;
-  releaseName: WriteAction<{ name: string; arioProcessId: string }>;
-  reassignName: WriteAction<{
+  setRecord: AoWriteAction<AoANTSetUndernameRecordParams>;
+  removeRecord: AoWriteAction<{ undername: string }>;
+  setBaseNameRecord: AoWriteAction<AoANTSetBaseNameRecordParams>;
+  setUndernameRecord: AoWriteAction<AoANTSetUndernameRecordParams>;
+  removeUndernameRecord: AoWriteAction<{ undername: string }>;
+  setTicker: AoWriteAction<{ ticker: string }>;
+  setDescription: AoWriteAction<{ description: string }>;
+  setKeywords: AoWriteAction<{ keywords: string[] }>;
+  setName: AoWriteAction<{ name: string }>;
+  setLogo: AoWriteAction<{ txId: string }>;
+  releaseName: AoWriteAction<{ name: string; arioProcessId: string }>;
+  reassignName: AoWriteAction<{
     name: string;
     arioProcessId: string;
     antProcessId: string;
   }>;
-  approvePrimaryNameRequest: WriteAction<{
+  approvePrimaryNameRequest: AoWriteAction<{
     name: string;
     address: string;
     arioProcessId: string;
   }>;
-  removePrimaryNames: WriteAction<{
+  removePrimaryNames: AoWriteAction<{
     names: string[];
     arioProcessId: string;
     notifyOwners?: boolean;
   }>;
 }
 
-/** utility type to ensure WriteOptions are appended to each parameter set */
-type WriteAction<P, R = AoMessageResult> = (
-  params: P,
-  options?: WriteOptions,
-) => Promise<R>;
-
 export type AoANTSetBaseNameRecordParams = {
   transactionId: string;
   ttlSeconds: number;

src/types/common.ts

@@ -135,3 +135,9 @@ export interface AOContract {
     signer: AoSigner;
   }): Promise<{ id: string; result?: K }>;
 }
+
+/** utility type to ensure WriteOptions are appended to each parameter set */
+export type AoWriteAction<P, R = AoMessageResult> = (
+  params: P,
+  options?: WriteOptions,
+) => Promise<R>;