Decorate wallet transactions for subsigners

Author: ScreamingHawk

packages/guard/src/signer.ts

@@ -25,6 +25,12 @@ export class GuardSigner implements signers.SapientSigner {
     return this.address
   }
 
+  async decorateTransactions(
+    bundle: commons.transaction.IntendedTransactionBundle,
+  ): Promise<commons.transaction.IntendedTransactionBundle> {
+    return Promise.resolve(bundle)
+  }
+
   async requestSignature(
     id: string,
     _message: BytesLike,

packages/signhub/package.json

@@ -14,6 +14,7 @@
     "test:coverage": "nyc yarn test"
   },
   "dependencies": {
+    "@0xsequence/core": "workspace:*",
     "ethers": "^5.5.2"
   },
   "peerDependencies": {},

packages/signhub/src/orchestrator.ts

@@ -1,4 +1,5 @@
 import { ethers } from "ethers"
+import { commons } from "@0xsequence/core"
 import { isSapientSigner, SapientSigner } from "./signers/signer"
 import { SignerWrapper } from "./signers/wrapper"
 
@@ -39,10 +40,11 @@ export function isSignerStatusPending(status: SignerStatus): status is SignerSta
 export const InitialSituation = "Initial"
 
 /**
- * It orchestrates the signing of a single digest by multiple signers.
+ * Orchestrates the signing of a single digests and transactions by multiple signers.
  * It can provide internal visibility of the signing process, and it also
  * provides the internal signers with additional information about the
- * message being signed.
+ * message being signed. Transaction decoration can be used to ensure on-chain state
+ * is correctly managed during the signing process.
  */
 export class Orchestrator {
   private observers: ((status: Status, metadata: Object) => void)[] = []
@@ -82,6 +84,15 @@ export class Orchestrator {
     ])
   }
 
+  async decorateTransactions(
+    bundle: commons.transaction.IntendedTransactionBundle,
+  ): Promise<commons.transaction.IntendedTransactionBundle> {
+    for (const signer of this.signers) {
+      bundle = await signer.decorateTransactions(bundle)
+    }
+    return bundle
+  }
+
   signMessage(args: {
     candidates?: string[],
     message: ethers.BytesLike,

packages/signhub/src/signers/signer.ts

@@ -1,9 +1,20 @@
 import { ethers } from "ethers"
+import { commons } from "@0xsequence/core"
 import { Status } from "../orchestrator"
 
 export interface SapientSigner {
   getAddress(): Promise<string>
 
+  /**
+   * Modify the transaction bundle before it is sent.
+   */
+  decorateTransactions(
+    bundle: commons.transaction.IntendedTransactionBundle,
+  ): Promise<commons.transaction.IntendedTransactionBundle>
+
+  /**
+   * Request a signature from the signer.
+   */
   requestSignature(
     id: string,
     message: ethers.BytesLike,
@@ -15,6 +26,9 @@ export interface SapientSigner {
     }
   ): Promise<boolean>
 
+  /**
+   * Notify the signer of a status change.
+   */
   notifyStatusChange(
     id: string,
     status: Status,

packages/signhub/src/signers/wrapper.ts

@@ -1,5 +1,6 @@
 
 import { ethers } from 'ethers'
+import { commons } from "@0xsequence/core"
 import { Status } from '../orchestrator'
 import { SapientSigner } from './signer'
 
@@ -10,6 +11,12 @@ export class SignerWrapper implements SapientSigner {
     return this.signer.getAddress()
   }
 
+  async decorateTransactions(
+    bundle: commons.transaction.IntendedTransactionBundle
+  ): Promise<commons.transaction.IntendedTransactionBundle> {
+      return bundle
+  }
+
   async requestSignature(
     _id: string,
     message: ethers.BytesLike,

packages/signhub/tests/orchestrator.spec.ts

@@ -1,6 +1,7 @@
 
 import * as chai from 'chai'
 import { ethers } from 'ethers'
+import { commons } from "@0xsequence/core"
 import { isSignerStatusPending, isSignerStatusRejected, isSignerStatusSigned, Orchestrator, Status } from '../src'
 import { SapientSigner } from '../src/signers'
 
@@ -109,6 +110,11 @@ describe('Orchestrator', () => {
       getAddress: async function (): Promise<string> {
         return brokenSignerEOA.address
       },
+      decorateTransactions(
+        bundle: commons.transaction.IntendedTransactionBundle,
+      ): Promise<commons.transaction.IntendedTransactionBundle> {
+        throw new Error('This is a broken signer.')
+      },
       requestSignature: async function (
         id: string,
         message: ethers.utils.BytesLike,
@@ -189,6 +195,11 @@ describe('Orchestrator', () => {
       getAddress: async function (): Promise<string> {
         return rejectSignerEOA.address
       },
+      decorateTransactions(
+        bundle: commons.transaction.IntendedTransactionBundle,
+      ): Promise<commons.transaction.IntendedTransactionBundle> {
+        throw new Error('This is a rejected signer.')
+      },
       requestSignature: async function (
         id: string,
         message: ethers.utils.BytesLike,
@@ -241,6 +252,11 @@ describe('Orchestrator', () => {
       getAddress: async function (): Promise<string> {
         return '0x1234'
       },
+      decorateTransactions(
+        bundle: commons.transaction.IntendedTransactionBundle,
+      ): Promise<commons.transaction.IntendedTransactionBundle> {
+        return Promise.resolve(bundle)
+      },
       requestSignature: async function (
         id: string,
         message: ethers.utils.BytesLike,
@@ -269,6 +285,11 @@ describe('Orchestrator', () => {
       getAddress: async function (): Promise<string> {
         return '0x1234'
       },
+      decorateTransactions(
+        bundle: commons.transaction.IntendedTransactionBundle,
+      ): Promise<commons.transaction.IntendedTransactionBundle> {
+        return Promise.resolve(bundle)
+      },
       requestSignature: async function (
         id: string,
         message: ethers.utils.BytesLike,
@@ -301,6 +322,11 @@ describe('Orchestrator', () => {
       getAddress: async function (): Promise<string> {
         return '0x1234'
       },
+      decorateTransactions(
+        bundle: commons.transaction.IntendedTransactionBundle,
+      ): Promise<commons.transaction.IntendedTransactionBundle> {
+        return Promise.resolve(bundle)
+      },
       requestSignature: async function (
         id: string,
         message: ethers.utils.BytesLike,
@@ -331,6 +357,11 @@ describe('Orchestrator', () => {
       getAddress: async function (): Promise<string> {
         return '0x5678'
       },
+      decorateTransactions(
+        bundle: commons.transaction.IntendedTransactionBundle,
+      ): Promise<commons.transaction.IntendedTransactionBundle> {
+        return Promise.resolve(bundle)
+      },
       requestSignature: async function (
         id: string,
         message: ethers.utils.BytesLike,
@@ -383,6 +414,11 @@ describe('Orchestrator', () => {
       getAddress: async function (): Promise<string> {
         return '0x1234'
       },
+      decorateTransactions(
+        bundle: commons.transaction.IntendedTransactionBundle,
+      ): Promise<commons.transaction.IntendedTransactionBundle> {
+        return Promise.resolve(bundle)
+      },
       requestSignature: async function (
         id: string,
         message: ethers.utils.BytesLike,

packages/wallet/src/orchestrator/wrapper.ts

@@ -13,6 +13,12 @@ export class SequenceOrchestratorWrapper implements signers.SapientSigner {
     return this.wallet.address
   }
 
+  async decorateTransactions(
+    bundle: commons.transaction.IntendedTransactionBundle
+  ): Promise<commons.transaction.IntendedTransactionBundle> {
+    return this.wallet.decorateTransactions(bundle)
+  }
+
   async requestSignature(
     _id: string,
     message: ethers.utils.BytesLike,

packages/wallet/src/wallet.ts

@@ -141,7 +141,12 @@ export class Wallet<
   async decorateTransactions(
     bundle: commons.transaction.IntendedTransactionBundle
   ): Promise<commons.transaction.IntendedTransactionBundle> {
-    if (await this.reader().isDeployed(this.address)) return bundle
+    const decorated = await this.orchestrator.decorateTransactions(bundle)
+    const unchanged = decorated === bundle
+
+    if (unchanged && await this.reader().isDeployed(this.address)) {
+      return bundle
+    }
 
     const deployTx = this.buildDeployTransaction()
 
@@ -151,12 +156,12 @@ export class Wallet<
     return {
       entrypoint: this.context.guestModule,
       chainId: this.chainId,
-      intent: bundle.intent,
+      intent: decorated.intent,
       transactions: [
         ...deployTx.transactions,
         {
-          to: bundle.entrypoint,
-          data: commons.transaction.encodeBundleExecData(bundle),
+          to: decorated.entrypoint,
+          data: commons.transaction.encodeBundleExecData(decorated),
           gasLimit: 0,
           delegateCall: false,
           revertOnError: true,