Add multisig Python SDK tooling, tutorial

aptos-move/framework/aptos-framework/doc/account.md

@@ -348,6 +348,10 @@ Second, this struct is signed by the new public key that the account owner wants
 knowledge of this new public key's associated secret key. These two signatures cannot be replayed in another
 context because they include the TXN's unique sequence number.
 
+Note that the challenge message to sign includes the <code><a href="account.md#0x1_account_RotationProofChallenge">RotationProofChallenge</a></code> type info prepended to the
+relevant bytes, such that serializing then signing only the below four struct fields will lead to rotation
+failure. For the verification implementation, see <code>aptos_stdlib::ed25519::signature_verify_strict_t()</code>.
+
 
 <pre><code><b>struct</b> <a href="account.md#0x1_account_RotationProofChallenge">RotationProofChallenge</a> <b>has</b> <b>copy</b>, drop
 </code></pre>

aptos-move/framework/aptos-framework/sources/account.move

@@ -68,6 +68,10 @@ module aptos_framework::account {
     /// Second, this struct is signed by the new public key that the account owner wants to rotate to, which proves
     /// knowledge of this new public key's associated secret key. These two signatures cannot be replayed in another
     /// context because they include the TXN's unique sequence number.
+    ///
+    /// Note that the challenge message to sign includes the `RotationProofChallenge` type info prepended to the
+    /// relevant bytes, such that serializing then signing only the below four struct fields will lead to rotation
+    /// failure. For the verification implementation, see `aptos_stdlib::ed25519::signature_verify_strict_t()`.
     struct RotationProofChallenge has copy, drop {
         sequence_number: u64, // the sequence number of the account whose key is being rotated
         originator: address, // the address of the account whose key is being rotated

aptos-move/move-examples/upgrade_and_govern/README.md

@@ -0,0 +1,4 @@
+# `UpgradeAndGovern`
+
+This directory contains two subsequent versions of the same package, as well as mock governance scripts.
+See the "Your First Multisig" tutorial for more.

aptos-move/move-examples/upgrade_and_govern/v1_0_0/Move.toml

@@ -0,0 +1,10 @@
+# :!:>manifest
+[package]
+name = 'UpgradeAndGovern'
+version = '1.0.0'
+
+[addresses]
+upgrade_and_govern = '_'
+
+[dependencies.AptosFramework]
+local = '../../../framework/aptos-framework' # <:!:manifest

aptos-move/move-examples/upgrade_and_govern/v1_0_0/sources/parameters.move

@@ -0,0 +1,32 @@
+// :!:>module
+/// Mock on-chain governance parameters.
+module upgrade_and_govern::parameters {
+
+    struct GovernanceParameters has key {
+        parameter_1: u64,
+        parameter_2: u64
+    }
+
+    const GENESIS_PARAMETER_1: u64 = 123;
+    const GENESIS_PARAMETER_2: u64 = 456;
+
+    fun init_module(
+        upgrade_and_govern: &signer
+    ) {
+        let governance_parameters = GovernanceParameters{
+            parameter_1: GENESIS_PARAMETER_1,
+            parameter_2: GENESIS_PARAMETER_2};
+        move_to<GovernanceParameters>(
+            upgrade_and_govern, governance_parameters);
+    }
+
+    public fun get_parameters():
+    (u64, u64)
+    acquires GovernanceParameters {
+        let governance_parameters_ref =
+            borrow_global<GovernanceParameters>(@upgrade_and_govern);
+        (governance_parameters_ref.parameter_1,
+         governance_parameters_ref.parameter_2)
+    }
+
+} // <:!:module

aptos-move/move-examples/upgrade_and_govern/v1_1_0/Move.toml

@@ -0,0 +1,10 @@
+# :!:>manifest
+[package]
+name = 'UpgradeAndGovern'
+version = '1.1.0'
+
+[addresses]
+upgrade_and_govern = '_'
+
+[dependencies.AptosFramework]
+local = '../../../framework/aptos-framework' # <:!:manifest

aptos-move/move-examples/upgrade_and_govern/v1_1_0/scripts/set_and_transfer.move

@@ -0,0 +1,18 @@
+// :!:>script
+script {
+    use upgrade_and_govern::parameters;
+    use upgrade_and_govern::transfer;
+
+    const PARAMETER_1: u64 = 300;
+    const PARAMETER_2: u64 = 200;
+
+    fun main(
+        upgrade_and_govern: &signer,
+        to_1: address,
+        to_2: address
+    ) {
+        parameters::set_parameters(
+            upgrade_and_govern, PARAMETER_1, PARAMETER_2);
+        transfer::transfer_octas(upgrade_and_govern, to_1, to_2);
+    }
+} // <:!:script

aptos-move/move-examples/upgrade_and_govern/v1_1_0/scripts/set_only.move

@@ -0,0 +1,14 @@
+// :!:>script
+script {
+    use upgrade_and_govern::parameters;
+
+    const PARAMETER_1: u64 = 500;
+    const PARAMETER_2: u64 = 700;
+
+    fun set_only(
+        upgrade_and_govern: &signer,
+    ) {
+        parameters::set_parameters(
+            upgrade_and_govern, PARAMETER_1, PARAMETER_2);
+    }
+} // <:!:script

aptos-move/move-examples/upgrade_and_govern/v1_1_0/sources/parameters.move

@@ -0,0 +1,49 @@
+/// Mock on-chain governance parameters.
+module upgrade_and_govern::parameters {
+
+    struct GovernanceParameters has key {
+        parameter_1: u64,
+        parameter_2: u64
+    }
+
+    const GENESIS_PARAMETER_1: u64 = 123;
+    const GENESIS_PARAMETER_2: u64 = 456;
+
+    fun init_module(
+        upgrade_and_govern: &signer
+    ) {
+        let governance_parameters = GovernanceParameters{
+            parameter_1: GENESIS_PARAMETER_1,
+            parameter_2: GENESIS_PARAMETER_2};
+        move_to<GovernanceParameters>(
+            upgrade_and_govern, governance_parameters);
+    }
+
+    public fun get_parameters():
+    (u64, u64)
+    acquires GovernanceParameters {
+        let governance_parameters_ref =
+            borrow_global<GovernanceParameters>(@upgrade_and_govern);
+        (governance_parameters_ref.parameter_1,
+         governance_parameters_ref.parameter_2)
+    }
+
+    // :!:>appended
+    use std::signer::address_of;
+
+    const E_INVALID_AUTHORITY: u64 = 0;
+
+    public entry fun set_parameters(
+        upgrade_and_govern: &signer,
+        parameter_1: u64,
+        parameter_2: u64
+    ) acquires GovernanceParameters {
+        assert!(address_of(upgrade_and_govern) == @upgrade_and_govern,
+                E_INVALID_AUTHORITY);
+        let governance_parameters_ref_mut =
+            borrow_global_mut<GovernanceParameters>(@upgrade_and_govern);
+        governance_parameters_ref_mut.parameter_1 = parameter_1;
+        governance_parameters_ref_mut.parameter_2 = parameter_2;
+    }
+
+} // <:!:appended

aptos-move/move-examples/upgrade_and_govern/v1_1_0/sources/transfer.move

@@ -0,0 +1,19 @@
+// :!:>module
+/// Mock coin transfer module that invokes governance parameters.
+module upgrade_and_govern::transfer {
+
+    use aptos_framework::aptos_coin::AptosCoin;
+    use aptos_framework::coin;
+    use upgrade_and_govern::parameters;
+
+    public entry fun transfer_octas(
+        from: &signer,
+        to_1: address,
+        to_2: address
+    ) {
+        let (amount_1, amount_2) = parameters::get_parameters();
+        coin::transfer<AptosCoin>(from, to_1, amount_1);
+        coin::transfer<AptosCoin>(from, to_2, amount_2);
+    }
+
+} // <:!:module