@massalabs/multisig-contract 0.0.2-dev.20260414091108

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 Dusa Labs
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,129 @@
+# Massa Multisignature Wallet
+
+The purpose of multisig wallets is to increase security by requiring multiple parties to agree on transactions before execution. Transactions can be executed only when confirmed by a predefined number of owners.
+
+Features
+Can hold Massa and all kinds of tokens
+Integration with web3 wallets 
+Interacting with any contracts
+ @dev Most important concepts:
+ *      Threshold/required: Number of required confirmations for a Multisig transaction.
+ *      Owners: List of addresses that control the Multisig. They are the only ones that
+        can submit, approve, and execute transactions.
+ *      UpgradeDelay: Delay necessary between an upgrade proposition and the actual upgrade
+ *      executionDelay: Delay necessary between the time the threshold is met for a specific transaction and its execution.
+ *      Id: Each transaction has a different ID to prevent replay attacks.
+ *      Signature: A valid signature of an owner of the Multisig for a transaction hash.
+ *      Owners can only be added/removed by the multisig (same for changing the threshold
+        and upgrading the contract)
+ *      Change the owners, required,& upgradeDelay to your needs in src/deploy.ts 
+
+The executionDelay starts once the threshold is met, and is not reset when another wallet approves the tx. It can be reset if a wallet revokes approval and the approval count goes below the threshold.
+
+Anyone can send coins to the multisig using the receiveCoins functions.
+Only owners can call submit, approve, execute & revoke functions.
+Only the multisig itself can call addOwner, removeOwner, replaceOwner, changeRequirement, changeExecutionDelay, changeUpgradeDelay, proposeUpgrade & upgrade functions. Thus, they can only be called by submitting the call through the multisig, approving & executing it.
+
+## Security
+
+The code was fully audited for security by a third party professional security firm.
+The report is publicly available as the [security_audit.pdf](security_audit.pdf) file at the root of the repository.
+
+## Build
+
+By default this will build all files in `assembly/contracts` directory.
+
+```shell
+npm run build
+```
+
+## Deploy the multisig
+
+Prerequisites :
+
+- You must add a `.env` file at the root of the repository with the following keys set to valid values:
+- `PRIVATE_KEY="wallet_private_key"`
+- `RPC_URL="https://..."` (optional, defaults to buildnet)
+
+These keys will be the ones used by the deployment script to interact with the blockchain.
+
+Adapt `required`, `owners` & `upgradeDelay` to your liking (cf. important concepts) in `src/deploy.ts`.
+
+The following command will build contracts in `assembly/contracts` directory and execute the deployment script
+`src/deploy.ts`. This script deploys `Multisig.wasm` directly and automatically runs its constructor.
+
+```shell
+npm run deploy
+```
+
+## Proposal lifecycle (important)
+
+Submitting a proposal does **not** count as an approval for the proposing owner. The proposer must call approve separately if they want their confirmation included toward the threshold.
+
+The approve flow only records confirmations. When the number of approvals reaches the threshold, the proposal is **not** executed automatically. Someone with the right to execute must call execute explicitly (and respect any `executionDelay` enforced on-chain after the threshold is met).
+
+These behaviors are intentional in the current design. Automatically approving on behalf of the submitter, or automatically executing once the threshold is reached, could be explored as future improvements but are not implemented today.
+
+## Create an add-member proposal
+
+The repository also includes a helper script to submit a multisig proposal that adds a new owner.
+
+```shell
+npm run propose:add-member -- <multisig-address> <new-member-address>
+```
+
+The script uses the same `.env` configuration as deployment and prints the submitted operation id plus the final events emitted by the contract.
+
+## Approve a proposal
+
+The repository also includes a helper script to approve an existing multisig proposal by id.
+
+```shell
+npm run approve:proposal -- <multisig-address> <proposal-id>
+```
+
+The script uses the same `.env` configuration as deployment and prints the approval operation id plus the final events emitted by the contract.
+
+## Execute a proposal
+
+The repository also includes a helper script to execute an existing multisig proposal by id.
+
+```shell
+npm run execute:proposal -- <multisig-address> <proposal-id>
+```
+
+The script uses the same `.env` configuration as deployment and prints the execution operation id plus the final events emitted by the contract.
+
+## List proposals
+
+The repository also includes a read-only helper script to retrieve all multisig proposals and their current statuses.
+
+```shell
+npm run list:proposals -- <multisig-address>
+```
+
+The script prints a JSON array with each proposal's id, target, method, value, approvals, timestamp, execution flag, and derived status.
+
+## Get multisig parameters
+
+The repository also includes a read-only helper script to retrieve the multisig members, threshold, and execution delay directly from storage.
+
+```shell
+npm run get:multisig-parameters -- <multisig-address>
+```
+
+The script prints a JSON object containing the `members`, `threshold`, and `delay`.
+
+## Unit tests
+
+The test framework documentation is available here: [as-pect docs](https://as-pect.gitbook.io/as-pect)
+
+```shell
+npm run test
+```
+
+## Format code
+
+```shell
+npm run fmt
+```

package/assembly/__tests__/as-pect.d.ts

@@ -0,0 +1 @@
+/// <reference types="@as-pect/assembly/types/as-pect" />

package/assembly/__tests__/basic-tests.spec.ts

@@ -0,0 +1,447 @@
+import {
+  submit,
+  approve,
+  constructor,
+  getTransactions,
+} from '../contracts/Multisig';
+import { Storage, mockAdminContext, Address } from '@massalabs/massa-as-sdk';
+import {
+  Args,
+  u64ToBytes,
+  stringToBytes,
+  bytesToString,
+  serializableObjectsArrayToBytes,
+  bytesToSerializableObjectArray,
+  Serializable,
+  Result,
+  bytesToU32,
+} from '@massalabs/as-types';
+import {
+  changeCallStack,
+  resetStorage,
+} from '@massalabs/massa-as-sdk/assembly/vm-mock/storage';
+import { Transaction } from '../structs/Transaction';
+import { getApprovalCount, hasApproved } from '../contracts/multisig-internals';
+import { OWNERS, REQUIRED } from '../storage/Multisig';
+
+// address of admin caller set in vm-mock. must match with adminAddress of @massalabs/massa-as-sdk/vm-mock/vm.js
+const deployerAddress = 'AU12UBnqTHDQALpocVBnkPNy7y5CndUJQTLutaVDDFgMJcq5kQiKq';
+
+// address of the contract set in vm-mock. must match with contractAddr of @massalabs/massa-as-sdk/vm-mock/vm.js
+const contractAddr = 'AS12BqZEQ6sByhRLyEuf0YbQmcF2PsDdkNNG1akBJu9XcjZA1eT';
+
+// nb of confirmations required
+const nbConfirmations: i32 = 2;
+
+// the multisig owners
+const owners: Array<string> = [
+  'A12UBnqTHDQALpocVBnkPNy7y5CndUJQTLutaVDDFgMJcq5kQiKq',
+  'AU1qDAxGJ387ETi9JRQzZWSPKYq4YPXrFvdiE4VoXUaiAt38JFEC',
+  'AU125TiSrnD2YatYfEyRAWnBdD7TEuVbvGFkFgDuaYc2bdKyqKtb',
+];
+
+// where operation funds are sent when a transaction operation is executed
+const destination = 'AU155TiSrnD2YatYfEyRAWnBdD7TEuVbvGFkFgDuaYc2bdKyqKtb';
+
+// owners declared to the constructor for testing.
+const ownerList = [owners[0], owners[1], owners[2]];
+
+// transactions
+const transactions: Array<Transaction> = [
+  new Transaction(new Address(destination), '', u64(15000), [], 0, false),
+  new Transaction(
+    new Address(destination),
+    'getValueAt',
+    u64(15000),
+    new Args().add(42).serialize(),
+    0,
+    false,
+  ),
+];
+
+// ======================================================== //
+// ====              HELPER FUNCTIONS                  ==== //
+// ======================================================== //
+
+function retrieveOperation(opIndex: i32): Transaction {
+  let operationList = bytesToSerializableObjectArray<Transaction>(
+    getTransactions([]),
+  ).unwrap();
+  return operationList[opIndex];
+}
+
+// string are not serializable by default, we need this helper class
+class SerializableString implements Serializable {
+  s: string;
+
+  constructor(s: string = '') {
+    this.s = s;
+  }
+
+  public serialize(): StaticArray<u8> {
+    return stringToBytes(this.s);
+  }
+
+  public deserialize(data: StaticArray<u8>, _offset: i32): Result<i32> {
+    this.s = bytesToString(data);
+    return new Result<i32>(0);
+  }
+}
+
+function switchUser(user: string): void {
+  changeCallStack(user + ' , ' + contractAddr);
+}
+
+beforeAll(() => {
+  resetStorage();
+  mockAdminContext(true);
+});
+
+describe('Multisig contract tests', () => {
+  test('constructor', () => {
+    // ---------------------------
+    // check invalid constructors
+
+    // 0 confirmations
+    expect(() => {
+      const serializedArgs = new Args()
+        .add<Array<string>>(ownerList)
+        .add(i32(0))
+        .add(u64(0))
+        .add(u64(0))
+        .serialize();
+      constructor(serializedArgs);
+    }).toThrow();
+
+    // no owners
+    expect(() => {
+      const serializedArgs = new Args()
+        .add<Array<string>>([])
+        .add(i32(1))
+        .add(u64(0))
+        .add(u64(0))
+        .serialize();
+      constructor(serializedArgs);
+    }).toThrow();
+
+    // no Delay
+    expect(() => {
+      const serializedArgs = new Args()
+        .add<Array<string>>([])
+        .add(i32(1))
+        .add(u64(0))
+        .serialize();
+      constructor(serializedArgs);
+    }).toThrow();
+
+    // invalid args
+    expect(() => {
+      constructor([]);
+    }).toThrow();
+
+    resetStorage();
+
+    // -------------------------------------------------------
+    // define a valid constructor for a 2:4 multisig
+    const serializedArgs = new Args()
+      .add<Array<string>>(ownerList)
+      .add(nbConfirmations)
+      .add(u64(0))
+      .add(u64(0))
+      .serialize();
+    constructor(serializedArgs);
+
+    // check the nb of confirmations required is properly stored
+    expect(bytesToU32(Storage.get(REQUIRED))).toBe(nbConfirmations);
+
+    // compare the array of addresses as string to the array of Address in storage
+    let serializableStringList: Array<SerializableString> = [];
+    for (let i = 0; i < ownerList.length; ++i)
+      serializableStringList.push(new SerializableString(ownerList[i]));
+    let ownersFromStorage = new Args(Storage.get(OWNERS))
+      .nextStringArray()
+      .unwrap();
+    let serializableOwnerStringList: Array<SerializableString> = [];
+    for (let i = 0; i < ownersFromStorage.length; ++i)
+      serializableOwnerStringList.push(
+        new SerializableString(ownersFromStorage[i].toString()),
+      );
+    expect(
+      serializableObjectsArrayToBytes<SerializableString>(
+        serializableOwnerStringList,
+      ),
+    ).toStrictEqual(
+      serializableObjectsArrayToBytes<SerializableString>(
+        serializableStringList,
+      ),
+    );
+
+    // check that there are no operation registered yet
+    let operationList = bytesToSerializableObjectArray<Transaction>(
+      getTransactions([]),
+    ).unwrap();
+    expect(operationList.length).toBe(0);
+  });
+
+  test('submit operation by non owner', () => {
+    // expect the operation submission to fail
+    expect(() => {
+      submit(new Args().add(transactions[0]).serialize());
+    }).toThrow();
+  });
+
+  test('submit transaction operation', () => {
+    // pick owners[1] as the operation creator
+    switchUser(owners[1]);
+
+    // expect the operation index to be 1
+    expect(submit(new Args().add(transactions[0]).serialize())).toStrictEqual(
+      u64ToBytes(0),
+    );
+
+    let transaction = retrieveOperation(0);
+
+    // check the transaction content
+    expect(transaction.to).toBe(new Address(destination));
+    expect(transaction.value).toBe(u64(15000));
+    expect(transaction.executed).toBe(false);
+  });
+
+  // non validated operation
+  test('confirm transaction operation [owners[0]]', () => {
+    // pick owners[1] as the operation creator
+    switchUser(owners[1]);
+
+    let confirmingOwnersIndexes: Array<u8>;
+    let opIndex: u64;
+
+    confirmingOwnersIndexes = [0];
+    opIndex = 1;
+
+    expect(submit(new Args().add(transactions[0]).serialize())).toStrictEqual(
+      u64ToBytes(opIndex),
+    );
+
+    let ownerAddress = owners[confirmingOwnersIndexes[0]];
+    switchUser(ownerAddress);
+    approve(new Args().add(opIndex).serialize());
+
+    switchUser(deployerAddress);
+    expect(hasApproved(opIndex, new Address(ownerAddress)));
+    expect(retrieveOperation(1).timestamp).toBe(0);
+  });
+
+  // validated operation
+  test('confirm transaction operation [owners[1], owners[2]]', () => {
+    // pick owners[1] as the operation creator
+    switchUser(owners[1]);
+
+    let confirmingOwnersIndexes: Array<u8>;
+    let opIndex: u64;
+
+    confirmingOwnersIndexes = [1, 2];
+    opIndex = 2;
+
+    expect(submit(new Args().add(transactions[0]).serialize())).toStrictEqual(
+      u64ToBytes(opIndex),
+    );
+
+    for (let i = 0; i < confirmingOwnersIndexes.length; ++i) {
+      let ownerAddress = owners[confirmingOwnersIndexes[i]];
+      switchUser(ownerAddress);
+      approve(new Args().add(opIndex).serialize());
+
+      expect(hasApproved(opIndex, new Address(ownerAddress)));
+    }
+
+    switchUser(deployerAddress);
+    expect(getApprovalCount(opIndex)).toBe(2);
+    expect(retrieveOperation(2).timestamp).toBeGreaterThan(0);
+  });
+
+  // validated operation 2
+  test('confirm transaction operation [owners[1], owners[2]]', () => {
+    // pick owners[1] as the operation creator
+    switchUser(owners[1]);
+
+    let confirmingOwnersIndexes: Array<u8>;
+    let opIndex: u64;
+
+    confirmingOwnersIndexes = [1, 2];
+    opIndex = 3;
+
+    expect(submit(new Args().add(transactions[0]).serialize())).toStrictEqual(
+      u64ToBytes(opIndex),
+    );
+
+    for (let i = 0; i < confirmingOwnersIndexes.length; ++i) {
+      let ownerAddress = owners[confirmingOwnersIndexes[i]];
+      switchUser(ownerAddress);
+      approve(new Args().add(opIndex).serialize());
+
+      expect(hasApproved(opIndex, new Address(ownerAddress)));
+    }
+
+    switchUser(deployerAddress);
+    expect(getApprovalCount(opIndex)).toBe(2);
+    expect(retrieveOperation(3).timestamp).toBeGreaterThan(0);
+  });
+
+  // test of the call operation constructor
+  test('submit call operation', () => {
+    // pick owners[1] as the operation creator
+    switchUser(owners[1]);
+
+    expect(submit(new Args().add(transactions[1]).serialize())).toStrictEqual(
+      u64ToBytes(4),
+    );
+
+    // check that the operation is correctly stored
+    let transaction = retrieveOperation(4);
+
+    // check the operation content
+    expect(transaction.to).toBe(new Address(destination));
+    expect(transaction.value).toBe(u64(15000));
+    expect(transaction.method).toBe('getValueAt');
+    expect(transaction.data).toStrictEqual(new Args().add(42).serialize());
+  });
+
+  // TODO: can't test transferCoins & call operation on massa for now
+  // // operation 2 is validated, let's execute it
+  // test('execute transaction operation with success', () => {
+  //   let destinationBalance = Coins.balanceOf(destination);
+  //   let contractBalance = Coins.balanceOf(contractAddr);
+  //   let initDestinationBalance = destinationBalance;
+  //   let initContractBalance = contractBalance;
+
+  //   switchUser(owners[1]);
+  //   generateEvent(
+  //     createEvent('BALANCES BEFORE', [
+  //       initDestinationBalance.toString(),
+  //       initContractBalance.toString(),
+  //     ]),
+  //   );
+
+  //   expect(() => {
+  //     execute(new Args().add(u64(2)).serialize());
+  //   }).not.toThrow();
+
+  //   // retrieve the operation and check that it is marked as executed
+  //   let transaction = retrieveOperation(i32(2));
+  //   expect(transaction.executed).toBe(true);
+
+  //   destinationBalance = Coins.balanceOf(destination);
+  //   contractBalance = Coins.balanceOf(contractAddr);
+  //   generateEvent(
+  //     createEvent('BALANCES AFTER', [
+  //       destinationBalance.toString(),
+  //       contractBalance.toString(),
+  //     ]),
+  //   );
+
+  //   // check that the transfer has been done
+  //   expect(destinationBalance).toBe(initDestinationBalance + 15000);
+  //   expect(contractBalance + 15000).toBe(initContractBalance);
+  // });
+
+  //   // operation 1 is not validated, let's try to execute it
+  //   test('execute transaction operation with failure', () => {
+  //     let destinationBalance = Coins.balanceOf(destination);
+  //     let contractBalance = Coins.balanceOf(contractAddr);
+  //     let initDestinationBalance = destinationBalance;
+  //     let initContractBalance = contractBalance;
+
+  //     switchUser(owners[1]);
+  //     generateEvent(
+  //       createEvent('BALANCES BEFORE', [
+  //         initDestinationBalance.toString(),
+  //         initContractBalance.toString(),
+  //       ]),
+  //     );
+
+  //     expect(() => {
+  //       execute(new Args().add(u64(1)).serialize());
+  //     }).toThrow();
+
+  //     // the operation is not supposed to be deleted
+  //     expect(() => {
+  //       retrieveOperation(i32(1));
+  //     }).not.toThrow();
+
+  //     destinationBalance = Coins.balanceOf(destination);
+  //     contractBalance = Coins.balanceOf(contractAddr);
+  //     generateEvent(
+  //       createEvent('BALANCES AFTER', [
+  //         destinationBalance.toString(),
+  //         contractBalance.toString(),
+  //       ]),
+  //     );
+
+  //     // check that the transfer has not been done
+  //     expect(destinationBalance).toBe(initDestinationBalance);
+  //     expect(contractBalance).toBe(initContractBalance);
+  //   });
+
+  //   // operation 3 is validated by owners[1] & owners[2].
+  //   // now owners[1] will revoke it and we will try to execute it.
+  //   test('revoke operation', () => {
+  //     let operationListLenght = bytesToSerializableObjectArray<Transaction>(
+  //       getTransactions([]),
+  //     ).unwrap().length;
+
+  //     let destinationBalance = Coins.balanceOf(destination);
+  //     let contractBalance = Coins.balanceOf(contractAddr);
+  //     let initDestinationBalance = destinationBalance;
+  //     let initContractBalance = contractBalance;
+
+  //     switchUser(owners[1]);
+  //     expect(() => {
+  //       revoke(new Args().add(u64(3)).serialize());
+  //     }).not.toThrow();
+
+  //     switchUser(deployerAddress);
+  //     generateEvent(
+  //       createEvent('BALANCES BEFORE', [
+  //         initDestinationBalance.toString(),
+  //         initContractBalance.toString(),
+  //       ]),
+  //     );
+
+  //     expect(() => {
+  //       execute(new Args().add(u64(3)).serialize());
+  //     }).toThrow();
+
+  //     // the operation should not have been deleted
+  //     let operationList = bytesToSerializableObjectArray<Transaction>(
+  //       getTransactions([]),
+  //     ).unwrap();
+  //     expect(operationList.length).toBe(operationListLenght);
+
+  //     // retrieve the operation in its current state in Storage
+  //     let operation = retrieveOperation(i32(3));
+
+  //     expect(operation.to).toBe(new Address(destination));
+  //     expect(operation.value).toBe(u64(15000));
+  //     expect(operation.executed).toBe(false);
+
+  //     destinationBalance = Coins.balanceOf(destination);
+  //     contractBalance = Coins.balanceOf(contractAddr);
+  //     generateEvent(
+  //       createEvent('BALANCES AFTER', [
+  //         destinationBalance.toString(),
+  //         contractBalance.toString(),
+  //       ]),
+  //     );
+
+  //     // check that the transfer has not been done
+  //     expect(destinationBalance).toBe(initDestinationBalance);
+  //     expect(contractBalance).toBe(initContractBalance);
+  //   });
+
+  test('check operation list', () => {
+    let operationList = bytesToSerializableObjectArray<Transaction>(
+      getTransactions([]),
+    ).unwrap();
+    expect(operationList.length).toBe(5);
+  });
+});