Decorate wallet transactions for subsigners

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,