FuelLabs · K1-R1 · Jan 19, 2023 · Oct 16, 2022 · Oct 17, 2022 · Oct 17, 2022
@@ -1,5 +1,3 @@
 [workspace]
 resolver = "2"
-members = [
-    "./project/multisig-contract",
-]
+members = ["./project/multisig-contract"]
@@ -7,7 +7,7 @@
 
 ## Overview
 
-A multi-signature wallet is a wallet that has multiple owners. In order to execute a transaction, a sufficient number of owners need to sign a Tx. Moreover, this implementation uses weighted owners which means that certain owners may have more "votes" when it comes to increasing the number of approvals in order to surpass the minimum threshold for execution.
+A multi-signature wallet is a wallet that has multiple owners. In order to execute a transaction, a sufficient number of owners need to sign a transaction. This implementation uses weighted owners which means that certain owners may have more "votes" when it comes to increasing the number of approvals in order to surpass the minimum threshold for execution. This implementation allows owners to be both Fuel and EVM addresses; by additionally supporting signatures over [EIP-191](https://eips.ethereum.org/EIPS/eip-191) formatted messages.
 
 More information can be found in the [specification](./SPECIFICATION.md).
 

@@ -0,0 +1,97 @@
+Table of Contents
+
+- [Overview](#overview)
+- [Use Cases](#use-cases)
+  - [Core Functionality](#core-functionality)
+    - [`cancel_transaction()`](#cancel_transaction)
+    - [`constructor()`](#constructor)
+    - [`execute_transaction()`](#execute_transaction)
+    - [`transfer()`](#transfer)
+  - [State Checks](#state-checks)
+    - [`nonce()`](#nonce)
+    - [`balance()`](#balance)
+  - [Utilities](#Utilities)
+    - [`transaction_hash()`](#transaction_hash)
+- [Sequence Diagram](#sequence-diagram)
+
+# Overview
+
+This document provides an overview of the application.
+
+It outlines the use cases, i.e., desirable functionality, in addition to requirements for the smart contracts.
+
+# Use Cases
+
+This section contains general information about the functionality of the application and thus does not touch upon any technical aspects.
+
+If you are interested in a functional overview then this is the section for you.
+
+#### Core Functionality
+
+##### `cancel_transaction()`
+
+1. Cancels the next transaction by spending the current nonce. This is both a safety mechanism enabling a user to explicitly render a previously shared signature useless, as well as a way of conveniently skipping a transaction.
+   1. If the caller is an owner, which requires the contract to have been initialised.
+
+##### `constructor()`
+
+1. Sets the parameters for approving a transaction and sets the owners of the multisig.
+   1. If the constructor hasn't already been called.
+   2. Requires the `threshold`; the number of approvals required for a transaction to occur.
+      1. If the `threshold` is not 0.
+   3. Requires the `users`; the information about the owners of the multisig
+      1. If none of the owners have the 0th address (0x00000...).
+      2. If none of the owners are set to have an approval weighting (number of approvals per owner) of 0.
+      3. If the sum of the owners' approval weightings is a value larger than the `threshold` parameter. This prevents the contract being setup when the owners can never submit enough approvals to allow a transaction.
+
+##### `execute_transaction()`
+
+1. Execute a transaction, formed from the parameters.
+   > **NOTE** This functionality is not yet fully implemented.
+   1. If the constructor has been called.
+   2. If signature recovery is successful.
+   3. If the recovered addresses are in ascending order.
+   4. If the number of approvals, from the owners whose addresses were recovered, meets the threshold.
+   5. Requires `data`; the data field of the transaction to be executed.
+   6. Requires `signatures`; The information for each of the signatures submitted to approve a specific transaction.
+   7. Requires `to`; The recipient of the transaction to be executed.
+   8. Requires `value`; The value sent in the transaction to be executed.
+
+##### `transfer()`
+
+1. Transfers assets, via a transaction formed from the parameters.
+   1. If the constructor has been called.
+   2. If signature recovery is successful.
+   3. If the recovered addresses are in ascending order.
+   4. If the number of approvals, from the owners whose addresses were recovered, meets the threshold.
+   5. Requires `asset_id`: the contract ID of the asset to be transferred.
+   6. Requires `data`; the data field of the transaction.
+   7. Requires `signatures`; The information for each of the signatures submitted to approve a specific transaction.
+   8. Requires `to`; The recipient of the transaction.
+   9. Requires `value`; The value sent in the transaction.
+      1. If the contract owns enough of the asset to be transferred.
+
+#### State Checks
+
+##### `nonce()`
+
+1. Returns the current nonce of the contract.
+
+##### `balance()`
+
+1. Returns the contract's balance of the specified asset.
+   1. Requires `asset_id`; The contract ID of the asset to check that balance of.
+
+#### Utilities
+
+##### `transaction_hash()`
+
+1. Returns the hash of a transaction, comprised of the parameters. This is a utility for getting a transaction hash to sign over.
+   1. Requires `data`; The data field of the transaction.
+   2. Requires `nonce`; The nonce field of the transaction.
+   3. Requires `to`; The recipient of the transaction.
+   4. Requires `value`; The value sent in the transaction.
+
+## Sequence Diagram
+
+![Multisig wallet Sequence Diagram](.docs/multisig-wallet-sequence-diagram.png)
@@ -7,6 +7,8 @@ license = "Apache-2.0"
 
 [dependencies]
 fuels = { version = "0.33.0", features = ["fuel-core-lib"] }
+rand = "0.8"
+sha3 = "0.10.6"
 tokio = { version = "1.12", features = ["rt", "macros"] }
 
 [[test]]

@@ -1,24 +1,50 @@
 library data_structures;
 
-pub struct User {
-    // Contracts cannot sign therefore restrict scope to Address
-    /// The wallet address of a user
-    identity: Address,
-    /// Number of approvals the user provides when approving.
-    /// The default is usually 1
-    weight: u64,
+use std::b512::B512;
+
+pub enum MessageFormat {
+    None: (),
+    EIP191PersonalSign: (),
+}
+
+pub enum MessagePrefix {
+    None: (),
+    Ethereum: (),
+}
+
+pub enum WalletType {
+    Fuel: (),
+    EVM: (),
+}
+
+pub struct SignatureInfo {
+    /// The type of formatting of the message that was signed.
+    message_format: MessageFormat,
+    /// The type of prefix prepended to the message that was signed.
+    message_prefix: MessagePrefix,
+    /// The signature generated by signing over a message hash with the format and prefix specified in the `format` and `prefix` fields.
+    signature: B512,
+    /// The wallet type of the signer of the message.
+    wallet_type: WalletType,
 }
 
 pub struct Transaction {
-    /// Unique identifier for the contract which prevents this Tx from being submitted to another
-    /// instance of the multisig
+    /// Unique identifier for the contract which prevents this transaction from being submitted to another
+    /// instance of the multisig.
     contract_identifier: ContractId,
-    /// Payload sent to destination  // TODO: change to vec when implemented
+    /// Payload sent to destination  // TODO: change to Bytes when implemented: https://github.com/FuelLabs/sway/pull/3454
     data: b256,
-    /// The recipient (output / contract) regarding the Tx details
+    /// The recipient (output / contract) regarding the transaction details.
     destination: Identity,
-    /// Value used to prevent double spending
+    /// Value used to prevent double spending.
     nonce: u64,
-    /// Amount of asset
+    /// Amount of asset.
     value: u64,
 }
+
+pub struct User {
+    /// The wallet address of a user.
+    address: b256,
+    /// The number of approvals the user provides when approving.
+    weight: u64,
+}
@@ -1,13 +1,20 @@
 library errors;
+
+pub enum AccessControlError {
+    CanOnlyBeAccessedByAnOwner: (),
+}
+
 pub enum ExecutionError {
     IncorrectSignerOrdering: (),
     InsufficientAssetAmount: (),
     InsufficientApprovals: (),
 }
+
 pub enum InitError {
     AddressCannotBeZero: (),
     CannotReinitialize: (),
     NotInitialized: (),
     ThresholdCannotBeZero: (),
+    TotalWeightCannotBeLessThanThreshold: (),
     WeightingCannotBeZero: (),
 }
@@ -1,7 +1,12 @@
 library events;
 
+pub struct CancelEvent {
+    cancelled_nonce: u64,
+    user: b256,
+}
+
 pub struct ExecutedEvent {
-    data: b256, // TODO: change to vector when implemented
+    data: b256, // TODO: change to Bytes when implemented: https://github.com/FuelLabs/sway/pull/3454
     nonce: u64,
     to: Identity,
     value: u64,

@@ -0,0 +1,93 @@
+library interface;
+
+dep data_structures;
+
+use data_structures::{SignatureInfo, User};
+
+abi MultiSignatureWallet {
+    /// Cancel the next transaction by spending the current nonce.
+    ///
+    /// # Reverts
+    ///
+    /// * When the caller is not setup as an owner.
+    #[storage(read, write)]
+    fn cancel_transaction();
+
+    /// The constructor initializes the necessary values and unlocks further functionality.
+    ///
+    /// # Arguments
+    ///
+    /// * `threshold` - The number of approvals required to enable a transaction to be sent.
+    /// * `users` - The users of the multisig, who can sign transactions to add their approval.
+    ///
+    /// # Reverts
+    ///
+    /// * When the constructor is called more than once.
+    /// * When the user address is the 0th address (0x00000...).
+    /// * When the threshold is set to 0.
+    /// * When an owner has an approval weight of 0.
+    /// * When the threshold is a value greater than the sum of the weights.
+    #[storage(read, write)]
+    fn constructor(threshold: u64, users: Vec<User>);
+
+    /// Execute a transaction formed from the `to`, `value` and `data` parameters if the signatures meet the
+    /// threshold requirement.
+    ///
+    /// # Arguments
+    ///
+    /// * `data` - The data field of the transaction.
+    /// * `signatures` - The information for each user's signature for a specific transaction.
+    /// * `to` - The recipient of the transaction.
+    /// * `value` - The value sent in the transaction.
+    ///
+    /// # Reverts
+    ///
+    /// - When the constructor has not been called to initialize the contract.
+    /// - When the amount of the asset being sent is greater than the balance in the contract.
+    /// - When the public key cannot be recovered from a signature.
+    /// - When the recovered addresses are not in ascending order (0x1 < 0x2 < 0x3...).
+    /// - When the total approval count is less than the required threshold for execution.
+    #[storage(read, write)]
+    fn execute_transaction(data: b256, signatures: Vec<SignatureInfo>, to: Identity, value: u64);
+
+    /// Transfers assets to outputs & contracts if the signatures meet the threshold requirement.
+    ///
+    /// # Arguments
+    ///
+    /// * `asset_id` - The contract ID of the asset to be transferred.
+    /// * `data` - The data field of the transaction.
+    /// * `signatures` - The information for each user's signature for a specific transaction.
+    /// * `to` - The recipient of the transaction.
+    /// * `value` - The value sent in the transaction.
+    ///
+    /// # Reverts
+    ///
+    /// - When the constructor has not been called to initialize the contract.
+    /// - When the amount of the asset being sent is greater than the balance in the contract.
+    /// - When the public key cannot be recovered from a signature.
+    /// - When the recovered addresses are not in ascending order (0x1 < 0x2 < 0x3...).
+    /// - When the total approval count is less than the required threshold for execution.
+    #[storage(read, write)]
+    fn transfer(asset_id: ContractId, data: b256, signatures: Vec<SignatureInfo>, to: Identity, value: u64);
+
+    /// Returns the current nonce in the contract
+    #[storage(read)]
+    fn nonce() -> u64;
+
+    /// Returns the contract's balance of the specified asset.
+    ///
+    /// # Arguments
+    ///
+    /// * `asset_id` - The contract ID of the asset to check that balance of.
+    fn balance(asset_id: ContractId) -> u64;
+
+    /// Takes in transaction data and hashes it into a unique tx hash.
+    ///
+    /// # Arguments
+    ///
+    /// * `data` - The data field of the transaction.
+    /// * `nonce` - The nonce field of the transaction.
+    /// * `to` - The recipient of the transaction.
+    /// * `value` - The value sent in the transaction.
+    fn transaction_hash(data: b256, nonce: u64, to: Identity, value: u64) -> b256;
+}