IDCOM-2089 Close Transaction Instruction (#213)

* feature: close_transaction implementation in program and client.

Author: rado0x54

packages/client/cli/src/service/cryptid/index.ts

@@ -8,7 +8,7 @@ import {
   CryptidClient,
 } from "@identity.com/cryptid";
 import { util } from "@identity.com/cryptid-core";
-import { ExecuteArrayResult } from "@identity.com/cryptid-core/dist/types/cryptid";
+import { TransactionArrayResult } from "@identity.com/cryptid-core/dist/types/cryptid";
 
 const KEY_RESERVE_AIRDROP_LAMPORTS = 500_000;
 
@@ -109,15 +109,13 @@ export const airdrop = async (
 const createCryptidTransaction = async (
   cryptid: CryptidClient,
   transaction: Transaction
-): Promise<ExecuteArrayResult> => {
+): Promise<TransactionArrayResult> => {
   if (cryptid.details.middlewares.length) {
     return cryptid.proposeAndExecute(transaction);
   } else {
     return {
-      executeTransactions: await cryptid
-        .directExecute(transaction)
-        .then((tx) => [tx]),
-      executeSigners: [],
+      transactions: await cryptid.directExecute(transaction).then((tx) => [tx]),
+      signers: [],
     };
   }
 };
@@ -126,13 +124,15 @@ export const signAndSendCryptidTransaction = async (
   cryptid: CryptidClient,
   transaction: Transaction
 ): Promise<string[]> => {
-  const { executeTransactions, executeSigners } =
-    await createCryptidTransaction(cryptid, transaction);
-  return executeTransactions.reduce(
+  const { transactions, signers } = await createCryptidTransaction(
+    cryptid,
+    transaction
+  );
+  return transactions.reduce(
     (promise, tx) =>
       // send the tx strictly after the previous one, and add the signature to the array
       promise.then((sigs) =>
-        cryptid.send(tx, executeSigners).then((sig) => [...sigs, sig])
+        cryptid.send(tx, signers).then((sig) => [...sigs, sig])
       ),
     Promise.resolve<string[]>([])
   );

packages/client/core/src/api/abstractCryptidClient.ts

@@ -17,7 +17,7 @@ import { didService } from "../lib/did";
 import { CryptidService } from "../service/cryptid";
 import { CryptidAccountDetails } from "../lib/CryptidAccountDetails";
 import { TransactionAccount, TransactionState } from "../types";
-import { ProposalResult, ExecuteArrayResult } from "../types/cryptid";
+import { ProposalResult, TransactionArrayResult } from "../types/cryptid";
 import { translateError } from "@project-serum/anchor";
 import { CryptidTransaction } from "../lib/CryptidTransaction";
 
@@ -75,7 +75,7 @@ export abstract class AbstractCryptidClient implements CryptidClient {
   async proposeAndExecute(
     transaction: Transaction,
     forceSingleTx = false
-  ): Promise<ExecuteArrayResult> {
+  ): Promise<TransactionArrayResult> {
     const service = await this.service();
 
     // TODO this is likely temporary - we should not force the client to have to know whether
@@ -86,8 +86,8 @@ export abstract class AbstractCryptidClient implements CryptidClient {
         transaction
       );
       return {
-        executeTransactions: [executeResult.executeTransaction],
-        executeSigners: executeResult.executeSigners,
+        transactions: [executeResult.transaction],
+        signers: executeResult.signers,
       };
     }
 
@@ -99,14 +99,11 @@ export abstract class AbstractCryptidClient implements CryptidClient {
     );
 
     return {
-      executeTransactions: [
+      transactions: [
         proposalResult.proposeTransaction,
-        executeResult.executeTransaction,
-      ],
-      executeSigners: [
-        ...proposalResult.proposeSigners,
-        ...executeResult.executeSigners,
+        executeResult.transaction,
       ],
+      signers: [...proposalResult.proposeSigners, ...executeResult.signers],
     };
   }
 
@@ -138,7 +135,7 @@ export abstract class AbstractCryptidClient implements CryptidClient {
   async execute(
     transactionAccountAddress: PublicKey,
     cryptidTransactionRepresentation?: CryptidTransaction
-  ): Promise<ExecuteArrayResult> {
+  ): Promise<TransactionArrayResult> {
     return this.service()
       .then((service) =>
         service.execute(
@@ -148,13 +145,28 @@ export abstract class AbstractCryptidClient implements CryptidClient {
         )
       )
       .then((result) => ({
-        executeTransactions: [result.executeTransaction],
-        executeSigners: result.executeSigners,
+        transactions: [result.transaction],
+        signers: result.signers,
       }));
   }
 
-  // TODO reinstate
-  // abstract cancelLarge(transactionAccount: PublicKey): Promise<string>;
+  async close(
+    transactionAccountAddress: PublicKey,
+    cryptidTransactionRepresentation?: CryptidTransaction
+  ): Promise<TransactionArrayResult> {
+    return this.service()
+      .then((service) =>
+        service.close(
+          this.details,
+          transactionAccountAddress,
+          cryptidTransactionRepresentation
+        )
+      )
+      .then((result) => ({
+        transactions: [result.transaction],
+        signers: result.signers,
+      }));
+  }
 
   /**
    * Send a signed transaction, and optionally wait for it to be confirmed.

packages/client/core/src/api/cryptidClient.ts

@@ -11,7 +11,7 @@ import { Wallet } from "../types/crypto";
 import { ProposalResult, TransactionAccount, TransactionState } from "../types";
 import { CryptidAccountDetails } from "../lib/CryptidAccountDetails";
 import { Middleware } from "../lib/Middleware";
-import { ExecuteArrayResult } from "../types/cryptid";
+import { TransactionArrayResult } from "../types/cryptid";
 import { CryptidTransaction } from "../lib/CryptidTransaction";
 
 export type PayerOption = "DID_PAYS" | "SIGNER_PAYS";
@@ -104,7 +104,7 @@ export interface CryptidClient {
   proposeAndExecute(
     transaction: Transaction,
     forceSingleTx?: boolean
-  ): Promise<ExecuteArrayResult>;
+  ): Promise<TransactionArrayResult>;
 
   /**
    * Propose a transaction for execution by cryptid.
@@ -146,10 +146,19 @@ export interface CryptidClient {
   execute(
     transactionAccountAddress: PublicKey,
     cryptidTransactionRepresentation?: CryptidTransaction
-  ): Promise<ExecuteArrayResult>;
+  ): Promise<TransactionArrayResult>;
 
-  // TODO Reinstate
-  // cancelLarge(transactionAccount: PublicKey): Promise<TransactionSignature>;
+  /**
+   * Execute a proposed transaction.
+   *
+   * The transaction must be in "Ready" state.
+   * @param transactionAccountAddress
+   * @param cryptidTransactionRepresentation
+   */
+  close(
+    transactionAccountAddress: PublicKey,
+    cryptidTransactionRepresentation?: CryptidTransaction
+  ): Promise<TransactionArrayResult>;
 
   /**
    * Retrieves the DID document for this Cryptid account

packages/client/core/src/lib/CryptidTransaction.ts

@@ -360,6 +360,33 @@ export class CryptidTransaction {
       .remainingAccounts(this.accountMetas);
   }
 
+  /**
+   * Close an existing cryptidTransaction
+   * @param program
+   * @param transactionAccountAddress
+   */
+  // TODO move transactionAccountAddress into constructor?
+  // The anchor MethodsBuilder type is not exposed
+  // eslint-disable-next-line @typescript-eslint/explicit-module-boundary-types
+  close(program: Program<Cryptid>, transactionAccountAddress: PublicKey) {
+    return program.methods
+      .closeTransaction(
+        this.controllerChainReferences,
+        this.cryptidAccount.bump,
+        this.cryptidAccount.index,
+        this.cryptidAccount.didAccountBump
+      )
+      .accounts({
+        cryptidAccount: this.cryptidAccount.address,
+        didProgram: DID_SOL_PROGRAM,
+        did: this.cryptidAccount.didAccount,
+        authority: this.authority,
+        destination: this.authority,
+        transactionAccount: transactionAccountAddress,
+      })
+      .remainingAccounts(this.accountMetasOnlyKeys);
+  }
+
   /**
    * Create and directly execute a cryptidTransaction
    * @param program

packages/client/core/src/service/cryptid.ts

@@ -26,7 +26,7 @@ import { DID_SOL_PROGRAM } from "@identity.com/sol-did-client";
 import { MiddlewareRegistry } from "./middlewareRegistry";
 import {
   ControllerPubkeys,
-  ExecuteResult,
+  TransactionResult,
   ProposalResult,
 } from "../types/cryptid";
 import { MiddlewareResult } from "../types/middleware";
@@ -181,7 +181,7 @@ export class CryptidService {
   private async executeMiddlewareInstructions(
     account: CryptidAccountDetails,
     transactionAccount: PublicKey,
-    stage: "Propose" | "Execute"
+    stage: "Propose" | "Execute" | "Close"
   ): Promise<MiddlewareResult> {
     const middlewareContexts =
       MiddlewareRegistry.get().getMiddlewareContexts(account);
@@ -198,8 +198,13 @@ export class CryptidService {
       cryptidAccountDetails: account,
     };
 
-    // Middlewares may have functions taht are executed on propose stage, on execute stage, or both
-    const middlewareFn = stage === "Propose" ? "onPropose" : "onExecute";
+    // Middlewares may have functions interface functions for propose, execute and close.
+    const middlewareFn =
+      stage === "Propose"
+        ? "onPropose"
+        : stage === "Close"
+        ? "onClose"
+        : "onExecute";
 
     // For each middleware, execute their onPropose or onExecute function
     const middlewareExecutions = middlewareContexts.map(
@@ -346,7 +351,7 @@ export class CryptidService {
   public async proposeAndExecuteTransaction(
     account: CryptidAccountDetails,
     transaction: Transaction
-  ): Promise<ExecuteResult> {
+  ): Promise<TransactionResult> {
     const transactionAccountKeypair = Keypair.generate();
     const cryptidTransaction = CryptidTransaction.fromSolanaInstructions(
       account,
@@ -390,8 +395,8 @@ export class CryptidService {
     );
 
     return {
-      executeTransaction,
-      executeSigners: [
+      transaction: executeTransaction,
+      signers: [
         transactionAccountKeypair,
         ...middlewareProposeResults.signers,
         ...middlewareExecuteResults.signers,
@@ -403,7 +408,7 @@ export class CryptidService {
     account: CryptidAccountDetails,
     transactionAccountAddress: PublicKey,
     cryptidTransaction?: CryptidTransaction
-  ): Promise<ExecuteResult> {
+  ): Promise<TransactionResult> {
     const middlewareResult = await this.executeMiddlewareInstructions(
       account,
       transactionAccountAddress,
@@ -421,8 +426,35 @@ export class CryptidService {
       .transaction();
 
     return {
-      executeTransaction,
-      executeSigners: [...middlewareResult.signers],
+      transaction: executeTransaction,
+      signers: [...middlewareResult.signers],
+    };
+  }
+
+  public async close(
+    account: CryptidAccountDetails,
+    transactionAccountAddress: PublicKey,
+    cryptidTransaction?: CryptidTransaction
+  ): Promise<TransactionResult> {
+    const middlewareResult = await this.executeMiddlewareInstructions(
+      account,
+      transactionAccountAddress,
+      "Close"
+    );
+
+    const resolvedCryptidTransaction =
+      cryptidTransaction ||
+      (await this.getCryptidTransaction(account, transactionAccountAddress));
+
+    const closeTransaction = await resolvedCryptidTransaction
+      .close(this.program, transactionAccountAddress)
+      .preInstructions(middlewareResult.instructions)
+      .signers(middlewareResult.signers)
+      .transaction();
+
+    return {
+      transaction: closeTransaction,
+      signers: [...middlewareResult.signers],
     };
   }
 

packages/client/core/src/types.ts

@@ -5,8 +5,8 @@ export { ExtendedCluster } from "./types/solana";
 export { Wallet } from "./types/crypto";
 export {
   ProposalResult,
-  ExecuteResult,
-  ExecuteArrayResult,
+  TransactionResult,
+  TransactionArrayResult,
   TransactionState,
 } from "./types/cryptid";
 export {

packages/client/core/src/types/cryptid.ts

@@ -24,14 +24,14 @@ export type ProposalResult = {
   cryptidTransactionRepresentation: CryptidTransaction;
 };
 
-export type ExecuteResult = {
-  executeTransaction: Transaction;
-  executeSigners: Signer[];
+export type TransactionResult = {
+  transaction: Transaction;
+  signers: Signer[];
 };
 
-export type ExecuteArrayResult = {
-  executeTransactions: Transaction[];
-  executeSigners: Signer[];
+export type TransactionArrayResult = {
+  transactions: Transaction[];
+  signers: Signer[];
 };
 
 export type ControllerAccountMetaInfo = [

packages/client/core/src/types/middleware.ts

@@ -34,4 +34,5 @@ export interface MiddlewareClient<C extends GenericMiddlewareParams> {
   createMiddleware(params: C): Promise<Transaction>;
   onPropose(params: ExecuteMiddlewareParams): Promise<MiddlewareResult>;
   onExecute(params: ExecuteMiddlewareParams): Promise<MiddlewareResult>;
+  onClose(params: ExecuteMiddlewareParams): Promise<MiddlewareResult>;
 }