Skip to content
🎉 Welcome to the new Aptos Docs! Click here to submit feedback!
Build
CLI
Working With Move Contracts
Multisig Governance Tutorial

Multisig Governance Tutorial

Background

This section builds upon the Arguments in JSON tutorial. If you have not done that, please complete that tutorial first.

This tutorial likewise references the CliArgs example package.

ℹ️

If you would like to follow along, start by completing the Arguments in JSON tutorial steps!

For this example, Ace and Bee will conduct governance operations from a 2-of-2 “multisig v2” account (an on-chain multisig account per multisig_account.move)

Account creation

Since Ace’s account was created during the Arguments in JSON tutorial, start by mining a vanity address account for Bee too:

Terminal
aptos key generate \
    --vanity-prefix 0xbee \
    --output-file bee.key
Output
Terminal
{
  "Result": {
    "PublicKey Path": "bee.key.pub",
    "PrivateKey Path": "bee.key",
    "Account Address:": "0xbeec980219d246581cef5166dc6ba5fb1e090c7a7786a5176d111a9029b16ddc"
  }
}
ℹ️

The exact account address should vary for each run, though the vanity prefix should not.

Store Bee’s address in a shell variable, so you can call it inline later on:

Terminal
# Your exact address should vary
bee_addr=0xbeec980219d246581cef5166dc6ba5fb1e090c7a7786a5176d111a9029b16ddc

Fund Bee’s account using the faucet:

Terminal
aptos account fund-with-faucet --account $bee_addr
Output
Terminal
{
  "Result": "Added 100000000 Octas to account beec980219d246581cef5166dc6ba5fb1e090c7a7786a5176d111a9029b16ddc"
}

Ace can now create a multisig account:

Terminal
aptos multisig create \
    --additional-owners $bee_addr \
    --num-signatures-required 2 \
    --private-key-file ace.key \
    --assume-yes
Output
Terminal
{
  "Result": {
    "multisig_address": "57478da34604655c68b1dcb89e4f4a9124b6c0ecc1c59a0931d58cc4e60ac5c5",
    "transaction_hash": "0x849cc756de2d3b57210f5d32ae4b5e7d1f80e5d376233885944b6f3cc2124a05",
    "gas_used": 1524,
    "gas_unit_price": 100,
    "sender": "acef1b9b7d4ab208b99fed60746d18dcd74865edb7eb3c3f1428233988e4ba46",
    "sequence_number": 5,
    "success": true,
    "timestamp_us": 1685078644186194,
    "version": 528428043,
    "vm_status": "Executed successfully"
  }
}

Store the multisig address in a shell variable:

Terminal
# Your address should vary
multisig_addr=0x57478da34604655c68b1dcb89e4f4a9124b6c0ecc1c59a0931d58cc4e60ac5c5

Inspect the multisig

Use the assorted multisig_account.move view functions to inspect the multisig:

Number of signatures required
aptos move view \
    --function-id 0x1::multisig_account::num_signatures_required \
    --args \
        address:"$multisig_addr"
Output
Terminal
{
  "Result": [
    "2"
  ]
}
Owners
aptos move view \
    --function-id 0x1::multisig_account::owners \
    --args \
        address:"$multisig_addr"
Output
Terminal
{
  "Result": [
    [
      "0xbeec980219d246581cef5166dc6ba5fb1e090c7a7786a5176d111a9029b16ddc",
      "0xacef1b9b7d4ab208b99fed60746d18dcd74865edb7eb3c3f1428233988e4ba46"
    ]
  ]
}
Last resolved sequence number
aptos move view \
    --function-id 0x1::multisig_account::last_resolved_sequence_number \
    --args \
        address:"$multisig_addr"
Output
Terminal
{
  "Result": [
    "0"
  ]
}
Next sequence number
aptos move view \
    --function-id 0x1::multisig_account::next_sequence_number \
    --args \
        address:"$multisig_addr"
Output
Terminal
{
  "Result": [
    "1"
  ]
}

Enqueue a publication transaction

The first multisig transaction enqueued will be a transaction for publication of the CliArgs example package. First, generate a publication payload entry function JSON file:

Command
aptos move build-publish-payload \
    --named-addresses test_account=$multisig_addr \
    --json-output-file publication.json \
    --assume-yes
Output
Terminal
{
  "Result": "Publication payload entry function JSON file saved to publication.json"
}

Now have Ace propose publication of the package from the multisig account, storing only the payload hash on-chain:

Command
aptos multisig create-transaction \
    --multisig-address $multisig_addr \
    --json-file publication.json \
    --store-hash-only \
    --private-key-file ace.key \
    --assume-yes
Output
Terminal
{
  "Result": {
    "transaction_hash": "0x70c75903f8e1b1c0069f1e84ef9583ad8000f24124b33a746c88d2b031f7fe2c",
    "gas_used": 510,
    "gas_unit_price": 100,
    "sender": "acef1b9b7d4ab208b99fed60746d18dcd74865edb7eb3c3f1428233988e4ba46",
    "sequence_number": 6,
    "success": true,
    "timestamp_us": 1685078836492390,
    "version": 528429447,
    "vm_status": "Executed successfully"
  }
}

Note that the last resolved sequence number is still 0 because no transactions have been resolved:

Last resolved sequence number
aptos move view \
    --function-id 0x1::multisig_account::last_resolved_sequence_number \
    --args \
        address:"$multisig_addr"
Output
Terminal
{
  "Result": [
    "0"
  ]
}

However, the next sequence number has been incremented because a transaction has been enqueued:

Next sequence number
aptos move view \
    --function-id 0x1::multisig_account::next_sequence_number \
    --args \
        address:"$multisig_addr"
Output
Terminal
{
  "Result": [
    "2"
  ]
}

The multisig transaction enqueued on-chain can now be inspected:

Get transaction
aptos move view \
    --function-id 0x1::multisig_account::get_transaction \
    --args \
        address:"$multisig_addr" \
        String:1
Output
Terminal
{
  "Result": [
    {
      "creation_time_secs": "1685078836",
      "creator": "0xacef1b9b7d4ab208b99fed60746d18dcd74865edb7eb3c3f1428233988e4ba46",
      "payload": {
        "vec": []
      },
      "payload_hash": {
        "vec": [
          "0x62b91159c1428c1ef488c7290771de458464bd665691d9653d195bc28e0d2080"
        ]
      },
      "votes": {
        "data": [
          {
            "key": "0xacef1b9b7d4ab208b99fed60746d18dcd74865edb7eb3c3f1428233988e4ba46",
            "value": true
          }
        ]
      }
    }
  ]
}

Note from the above result that no payload is stored on-chain, and that Ace implicitly approved the transaction (voted true) upon the submission of the proposal.

Enqueue a governance parameter transaction

Now have Bee enqueue a governance parameter setter transaction, storing the entire transaction payload on-chain:

Command
aptos multisig create-transaction \
    --multisig-address $multisig_addr \
    --function-id $multisig_addr::cli_args::set_vals \
    --type-args \
        0x1::account::Account \
        0x1::chain_id::ChainId \
    --args \
        u8:123 \
        "bool:[false, true, false, false]" \
        'address:[["0xace", "0xbee"], ["0xcad"], []]' \
    --private-key-file bee.key \
    --assume-yes
Output
Terminal
{
  "Result": {
    "transaction_hash": "0xd0a348072d5bfc5a2e5d444f92f0ecc10b978dad720b174303bc6d91342f27ec",
    "gas_used": 511,
    "gas_unit_price": 100,
    "sender": "beec980219d246581cef5166dc6ba5fb1e090c7a7786a5176d111a9029b16ddc",
    "sequence_number": 0,
    "success": true,
    "timestamp_us": 1685078954841650,
    "version": 528430315,
    "vm_status": "Executed successfully"
  }
}

Note the next sequence number has been incremented again:

Next sequence number
aptos move view \
    --function-id 0x1::multisig_account::next_sequence_number \
    --args \
        address:"$multisig_addr"
Output
Terminal
{
  "Result": [
    "3"
  ]
}

Now both the publication and parameter transactions are pending:

Get pending transactions
aptos move view \
    --function-id 0x1::multisig_account::get_pending_transactions \
    --args \
        address:"$multisig_addr"
Output
Terminal
{
  "Result": [
    [
      {
        "creation_time_secs": "1685078836",
        "creator": "0xacef1b9b7d4ab208b99fed60746d18dcd74865edb7eb3c3f1428233988e4ba46",
        "payload": {
          "vec": []
        },
        "payload_hash": {
          "vec": [
            "0x62b91159c1428c1ef488c7290771de458464bd665691d9653d195bc28e0d2080"
          ]
        },
        "votes": {
          "data": [
            {
              "key": "0xacef1b9b7d4ab208b99fed60746d18dcd74865edb7eb3c3f1428233988e4ba46",
              "value": true
            }
          ]
        }
      },
      {
        "creation_time_secs": "1685078954",
        "creator": "0xbeec980219d246581cef5166dc6ba5fb1e090c7a7786a5176d111a9029b16ddc",
        "payload": {
          "vec": [
            "0x0057478da34604655c68b1dcb89e4f4a9124b6c0ecc1c59a0931d58cc4e60ac5c508636c695f61726773087365745f76616c7302070000000000000000000000000000000000000000000000000000000000000001076163636f756e74074163636f756e740007000000000000000000000000000000000000000000000000000000000000000108636861696e5f696407436861696e49640003017b0504000100006403020000000000000000000000000000000000000000000000000000000000000ace0000000000000000000000000000000000000000000000000000000000000bee010000000000000000000000000000000000000000000000000000000000000cad00"
          ]
        },
        "payload_hash": {
          "vec": []
        },
        "votes": {
          "data": [
            {
              "key": "0xbeec980219d246581cef5166dc6ba5fb1e090c7a7786a5176d111a9029b16ddc",
              "value": true
            }
          ]
        }
      }
    ]
  ]
}

Execute the publication transaction

Since only Ace has voted on the publication transaction (which he implicitly approved upon proposing) the transaction can’t be executed yet:

Can be executed
aptos move view \
    --function-id 0x1::multisig_account::can_be_executed \
    --args \
        address:"$multisig_addr" \
        String:1
Output
Terminal
{
  "Result": [
    false
  ]
}

Before Bee votes, however, she verifies that the payload hash stored on-chain matches the publication entry function JSON file:

Verifying transaction proposal
aptos multisig verify-proposal \
    --multisig-address $multisig_addr \
    --json-file publication.json \
    --sequence-number 1
Output
Terminal
{
  "Result": {
    "Status": "Transaction match",
    "Multisig transaction": {
      "creation_time_secs": "1685078836",
      "creator": "0xacef1b9b7d4ab208b99fed60746d18dcd74865edb7eb3c3f1428233988e4ba46",
      "payload": {
        "vec": []
      },
      "payload_hash": {
        "vec": [
          "0x62b91159c1428c1ef488c7290771de458464bd665691d9653d195bc28e0d2080"
        ]
      },
      "votes": {
        "data": [
          {
            "key": "0xacef1b9b7d4ab208b99fed60746d18dcd74865edb7eb3c3f1428233988e4ba46",
            "value": true
          }
        ]
      }
    }
  }
}

Since Bee has verified that the on-chain payload hash checks out against her locally-compiled package publication JSON file, she votes yes:

Approving transaction
aptos multisig approve \
    --multisig-address $multisig_addr \
    --sequence-number 1 \
    --private-key-file bee.key \
    --assume-yes
Output
Terminal
{
  "Result": {
    "transaction_hash": "0xa5fb49f1077de6aa6d976e6bcc05e4c50c6cd061f1c87e8f1ea74e7a04a06bd1",
    "gas_used": 6,
    "gas_unit_price": 100,
    "sender": "beec980219d246581cef5166dc6ba5fb1e090c7a7786a5176d111a9029b16ddc",
    "sequence_number": 1,
    "success": true,
    "timestamp_us": 1685079892130861,
    "version": 528437204,
    "vm_status": "Executed successfully"
  }
}

Now the transaction can be executed:

Can be executed
aptos move view \
    --function-id 0x1::multisig_account::can_be_executed \
    --args \
        address:"$multisig_addr" \
        String:1
Output
Terminal
{
  "Result": [
    true
  ]
}

Now either Ace or Bee can invoke the publication transaction from the multisig account, passing the full transaction payload since only the hash was stored on-chain:

Publication
aptos multisig execute-with-payload \
    --multisig-address $multisig_addr \
    --json-file publication.json \
    --private-key-file bee.key \
    --max-gas 10000 \
    --assume-yes
ℹ️

Pending the resolution of #8304, the transaction simulator (which is used to estimate gas costs) is broken for multisig transactions, so you will have to manually specify a max gas amount.

Output

Also pending the resolution of #8304, the CLI output for a successful multisig publication transaction execution results in an API error if only the payload hash has been stored on-chain, but the transaction can be manually verified using an explorer.

Execute the governance parameter transaction

Since only Bee has voted on the governance parameter transaction (which she implicitly approved upon proposing), the transaction can’t be executed yet:

Can be executed
aptos move view \
    --function-id 0x1::multisig_account::can_be_executed \
    --args \
        address:"$multisig_addr" \
        String:2
Output
Terminal
{
  "Result": [
    false
  ]
}

Before Ace votes, however, he verifies that the payload stored on-chain matches the function arguments he expects:

Verifying transaction proposal
aptos multisig verify-proposal \
    --multisig-address $multisig_addr \
    --function-id $multisig_addr::cli_args::set_vals \
    --type-args \
        0x1::account::Account \
        0x1::chain_id::ChainId \
    --args \
        u8:123 \
        "bool:[false, true, false, false]" \
        'address:[["0xace", "0xbee"], ["0xcad"], []]' \
    --sequence-number 2
Output
Terminal
{
  "Result": {
    "Status": "Transaction match",
    "Multisig transaction": {
      "creation_time_secs": "1685078954",
      "creator": "0xbeec980219d246581cef5166dc6ba5fb1e090c7a7786a5176d111a9029b16ddc",
      "payload": {
        "vec": [
          "0x0057478da34604655c68b1dcb89e4f4a9124b6c0ecc1c59a0931d58cc4e60ac5c508636c695f61726773087365745f76616c7302070000000000000000000000000000000000000000000000000000000000000001076163636f756e74074163636f756e740007000000000000000000000000000000000000000000000000000000000000000108636861696e5f696407436861696e49640003017b0504000100006403020000000000000000000000000000000000000000000000000000000000000ace0000000000000000000000000000000000000000000000000000000000000bee010000000000000000000000000000000000000000000000000000000000000cad00"
        ]
      },
      "payload_hash": {
        "vec": []
      },
      "votes": {
        "data": [
          {
            "key": "0xbeec980219d246581cef5166dc6ba5fb1e090c7a7786a5176d111a9029b16ddc",
            "value": true
          }
        ]
      }
    }
  }
}

Note that the verification fails if he modifies even a single argument:

Failed transaction verification with modified u8
aptos multisig verify-proposal \
    --multisig-address $multisig_addr \
    --function-id $multisig_addr::cli_args::set_vals \
    --type-args \
        0x1::account::Account \
        0x1::chain_id::ChainId \
    --args \
        u8:200 \
        "bool:[false, true, false, false]" \
        'address:[["0xace", "0xbee"], ["0xcad"], []]' \
    --sequence-number 2
Output
Terminal
{
  "Error": "Unexpected error: Transaction mismatch: The transaction you provided has a payload hash of 0xe494b0072d6f940317344967cf0e818c80082375833708c773b0275f3ad07e51, but the on-chain transaction proposal you specified has a payload hash of 0x070ed7c3f812f25f585461305d507b96a4e756f784e01c8c59901871267a1580. For more info, see https://aptos.dev/move/move-on-aptos/cli#multisig-governance"
}

Ace approves the transaction:

Approving transaction
aptos multisig approve \
    --multisig-address $multisig_addr \
    --sequence-number 2 \
    --private-key-file ace.key \
    --assume-yes
Output
Terminal
{
  "Result": {
    "transaction_hash": "0x233427d95832234fa13dddad5e0b225d40168b4c2c6b84f5255eecc3e68401bf",
    "gas_used": 6,
    "gas_unit_price": 100,
    "sender": "acef1b9b7d4ab208b99fed60746d18dcd74865edb7eb3c3f1428233988e4ba46",
    "sequence_number": 7,
    "success": true,
    "timestamp_us": 1685080266378400,
    "version": 528439883,
    "vm_status": "Executed successfully"
  }
}

Since the payload was stored on-chain, it is not required to execute the pending transaction:

Execution
aptos multisig execute \
    --multisig-address $multisig_addr \
    --private-key-file ace.key \
    --max-gas 10000 \
    --assume-yes
Output
Terminal
{
  "Result": {
    "transaction_hash": "0xbc99f929708a1058b223aa880d04607a78ebe503367ec4dab23af4a3bdb541b2",
    "gas_used": 505,
    "gas_unit_price": 100,
    "sender": "acef1b9b7d4ab208b99fed60746d18dcd74865edb7eb3c3f1428233988e4ba46",
    "sequence_number": 8,
    "success": true,
    "timestamp_us": 1685080344045461,
    "version": 528440423,
    "vm_status": "Executed successfully"
Arguments in JSON TutorialTrying Things On-Chain