add interface for multisig account wallet

package.json

@@ -43,6 +43,10 @@
       "types": "./types/src/protocols/index.d.ts",
       "default": "./src/protocols/index.js"
     },
+    "./multisig": {
+      "types": "./types/src/multisig/index.d.ts",
+      "default": "./src/multisig/index.js"
+    },
     "./package": {
       "default": "./package.json"
     }

src/multisig/i-multisig-owner-management.js

@@ -0,0 +1,82 @@
+// Copyright 2024 Tether Operations Limited
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+'use strict'
+
+import { NotImplementedError } from '../errors.js'
+
+/** @typedef {import('./wallet-account-read-only-multisig.js').MultisigProposal} MultisigProposal */
+
+/** @typedef {import('../errors.js').SignerError} SignerError */
+
+/**
+ * @typedef {Object} MultisigOptions
+ * @property {number} threshold - The new amount of approvals required to execute a transaction.
+ */
+
+/**
+ * Optional owner-management surface for multisig accounts whose owner set is mutable
+ * (e.g. account-abstraction wallets). Chains whose owner set is fixed at creation —
+ * such as Bitcoin script multisig, where the participants are committed in the redeem
+ * script — do not implement this interface.
+ *
+ * @interface
+ */
+export class IMultisigOwnerManagement {
+  /**
+   * Proposes adding a new owner to the multisig wallet account.
+   *
+   * @param {string} owner - The owner's address.
+   * @param {MultisigOptions} [options] - The multisig options.
+   * @returns {Promise<MultisigProposal>} The multisig proposal.
+   * @throws {SignerError} If the signer is not an owner of the multisig account.
+   */
+  async addOwner (owner, options) {
+    throw new NotImplementedError('addOwner(owner, options)')
+  }
+
+  /**
+   * Proposes removing an owner from the multisig wallet account.
+   *
+   * @param {string} owner - The owner's address.
+   * @param {MultisigOptions} [options] - The multisig options.
+   * @returns {Promise<MultisigProposal>} The multisig proposal.
+   * @throws {SignerError} If the signer is not an owner of the multisig account.
+   */
+  async removeOwner (owner, options) {
+    throw new NotImplementedError('removeOwner(owner, options)')
+  }
+
+  /**
+   * Proposes replacing an owner with a different one.
+   *
+   * @param {string} oldOwner - The old owner.
+   * @param {string} newOwner - The new owner.
+   * @returns {Promise<MultisigProposal>} The multisig proposal.
+   * @throws {SignerError} If the signer is not an owner of the multisig account.
+   */
+  async swapOwner (oldOwner, newOwner) {
+    throw new NotImplementedError('swapOwner(oldOwner, newOwner)')
+  }
+
+  /**
+   * Proposes changing the signature threshold.
+   *
+   * @param {number} newThreshold - The new threshold.
+   * @returns {Promise<MultisigProposal>} The multisig proposal.
+   * @throws {SignerError} If the signer is not an owner of the multisig account.
+   */
+  async changeThreshold (newThreshold) {
+    throw new NotImplementedError('changeThreshold(newThreshold)')
+  }
+}

src/multisig/i-multisig-transport.js

@@ -0,0 +1,128 @@
+// Copyright 2024 Tether Operations Limited
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+'use strict'
+
+import { NotImplementedError } from '../errors.js'
+
+/**
+ * A message proposal to share with the other owners for them to confirm.
+ *
+ * @typedef {Object} MultisigTransportMessageInput
+ * @property {string} message - The message to sign.
+ * @property {string} signature - The submitting owner's signature over the message.
+ */
+
+/**
+ * A shared transaction proposal returned by the transport. The concrete payload is
+ * chain-specific and opaque to the transport: an implementation persists whatever the
+ * chain's execution layer produced and returns it intact, alongside the owner
+ * confirmations collected so far.
+ *
+ * @typedef {Object} MultisigTransportProposal
+ * @property {unknown[]} confirmations - The owner confirmations (signatures) collected so far.
+ */
+
+/**
+ * A shared message proposal returned by the transport, alongside the owner confirmations
+ * collected so far. As with proposals, any further fields are chain-specific.
+ *
+ * @typedef {Object} MultisigTransportMessage
+ * @property {unknown[]} confirmations - The owner confirmations (signatures) collected so far.
+ */
+
+/**
+ * Transport for sharing multisig calldata between the owners of a multisig account.
+ *
+ * A transport distributes transaction proposals and message proposals (and their
+ * confirmations) amongst the owners of a multisig account, so that signers running on
+ * separate machines can coordinate without a shared process. It is chain-agnostic: the
+ * proposal and message payloads are opaque to the transport and interpreted by each
+ * chain's multisig package, so the same transport can back account-abstraction, UTXO
+ * (PSBT) or other multisig wallets. Plug in a custom backend (a hosted service, a
+ * database, a peer-to-peer channel, etc.) by implementing this interface.
+ *
+ * Implementations that serialize the payloads themselves (rather than handing them to an
+ * SDK that already does it) can pass them through {@link toTransportJson} to convert native
+ * values such as BigInt into JSON-safe forms before persisting or transmitting them.
+ *
+ * @interface
+ * @template [TProposal=Record<string, unknown>]
+ * @template [TMessage=MultisigTransportMessageInput]
+ * @template [TProposalResponse=MultisigTransportProposal]
+ * @template [TMessageResponse=MultisigTransportMessage]
+ */
+export class IMultisigTransport {
+  /**
+   * Submits a new transaction proposal so the other owners can confirm it.
+   *
+   * @param {TProposal} proposal - The signed transaction proposal to share. Opaque to the transport, which must persist it so {@link getProposal} can return it intact.
+   * @returns {Promise<void>}
+   */
+  async submitProposal (proposal) {
+    throw new NotImplementedError('submitProposal(proposal)')
+  }
+
+  /**
+   * Returns a transaction proposal by its identifier.
+   *
+   * @param {string} proposalId - The proposal's identifier.
+   * @returns {Promise<TProposalResponse | null>} The proposal, or null if it has not been found.
+   */
+  async getProposal (proposalId) {
+    throw new NotImplementedError('getProposal(proposalId)')
+  }
+
+  /**
+   * Adds an owner's confirmation (signature) to an existing transaction proposal.
+   *
+   * @param {string} proposalId - The proposal's identifier.
+   * @param {string} signature - The owner's signature over the proposal.
+   * @returns {Promise<void>}
+   */
+  async confirmProposal (proposalId, signature) {
+    throw new NotImplementedError('confirmProposal(proposalId, signature)')
+  }
+
+  /**
+   * Submits a new message proposal so the other owners can confirm it.
+   *
+   * @param {string} accountAddress - The multisig account's address.
+   * @param {TMessage} message - The message proposal to share.
+   * @returns {Promise<void>}
+   */
+  async submitMessage (accountAddress, message) {
+    throw new NotImplementedError('submitMessage(accountAddress, message)')
+  }
+
+  /**
+   * Returns a message proposal by its hash.
+   *
+   * @param {string} messageId - The message's hash.
+   * @returns {Promise<TMessageResponse | null>} The message, or null if it has not been found.
+   */
+  async getMessage (messageId) {
+    throw new NotImplementedError('getMessage(messageId)')
+  }
+
+  /**
+   * Adds an owner's confirmation (signature) to an existing message proposal.
+   *
+   * @param {string} messageId - The message's hash.
+   * @param {string} signature - The owner's signature over the message.
+   * @returns {Promise<void>}
+   */
+  async confirmMessage (messageId, signature) {
+    throw new NotImplementedError('confirmMessage(messageId, signature)')
+  }
+}

src/multisig/index.js

@@ -0,0 +1,37 @@
+// Copyright 2024 Tether Operations Limited
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+'use strict'
+
+/** @typedef {import('./wallet-account-read-only-multisig.js').MultisigInfo} MultisigInfo */
+/** @typedef {import('./wallet-account-read-only-multisig.js').MultisigProposal} MultisigProposal */
+/** @typedef {import('./wallet-account-read-only-multisig.js').MultisigMessage} MultisigMessage */
+/** @typedef {import('../wallet-account.js').KeyPair} KeyPair */
+
+/** @typedef {import('./wallet-account-multisig.js').MultisigTransactionOptions} MultisigTransactionOptions */
+/** @typedef {import('./wallet-account-multisig.js').MultisigMessageProposal} MultisigMessageProposal */
+/** @typedef {import('./i-multisig-owner-management.js').MultisigOptions} MultisigOptions */
+
+/** @typedef {import('./i-multisig-transport.js').MultisigTransportProposal} MultisigTransportProposal */
+/** @typedef {import('./i-multisig-transport.js').MultisigTransportMessage} MultisigTransportMessage */
+/** @typedef {import('./i-multisig-transport.js').MultisigTransportMessageInput} MultisigTransportMessageInput */
+
+export { IWalletAccountReadOnlyMultisig } from './wallet-account-read-only-multisig.js'
+
+export { IWalletAccountMultisig } from './wallet-account-multisig.js'
+
+export { IMultisigOwnerManagement } from './i-multisig-owner-management.js'
+
+export { IMultisigTransport } from './i-multisig-transport.js'
+
+export { toTransportJson } from './transport-serialization.js'

src/multisig/transport-serialization.js

@@ -0,0 +1,62 @@
+// Copyright 2024 Tether Operations Limited
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+'use strict'
+
+/**
+ * Converts a byte array to a 0x-prefixed lowercase hex string.
+ *
+ * @param {Uint8Array} bytes - The byte array to encode.
+ * @returns {string} The 0x-prefixed hex encoding.
+ */
+function bytesToHex (bytes) {
+  let hex = '0x'
+  for (const byte of bytes) {
+    hex += byte.toString(16).padStart(2, '0')
+  }
+  return hex
+}
+
+/**
+ * Recursively converts a value into a JSON-safe form so it survives JSON.stringify: every BigInt
+ * becomes its decimal string and every byte array (Uint8Array, including Buffer) becomes a
+ * 0x-prefixed lowercase hex string. Arrays and plain objects are converted entry by entry; all
+ * other values are returned unchanged.
+ *
+ * The conversion is one-way: there is no generic inverse, so a consumer that needs the original
+ * types back restores them per field (it knows which fields are amounts, byte strings, etc.).
+ *
+ * @param {unknown} value - The value to convert (object, array, or primitive).
+ * @returns {unknown} A JSON-safe copy of the value.
+ */
+export function toTransportJson (value) {
+  if (typeof value === 'bigint') {
+    return value.toString()
+  }
+
+  if (value instanceof Uint8Array) {
+    return bytesToHex(value)
+  }
+
+  if (Array.isArray(value)) {
+    return value.map(toTransportJson)
+  }
+
+  if (value !== null && typeof value === 'object') {
+    return Object.fromEntries(
+      Object.entries(value).map(([key, entry]) => [key, toTransportJson(entry)])
+    )
+  }
+
+  return value
+}